contact-dots

¿Qué hace contact-dots?

Coloca puntos en las manos, extremidades, pies y pelvis de cada personaje (y en cualquier otra cosa que nombres), luego mide, fotograma a fotograma en Blender sin interfaz gráfica, la distancia desde cada punto hasta una superficie, la distancia entre puntos y el ángulo entre direcciones. Escribe dots.json, imprime un breve resumen y renderiza dots-sheet.png (un primer plano por cada verificación y por la peor penetración).

Nunca cambia un archivo fuente y escribe únicamente en la carpeta de salida que nombres.

Cuándo usarlo

• "¿Está realmente su palma derecha sobre su muslo izquierdo en el fotograma 40?" (contacto corporal, touch)
• "¿Entra algún dedo dentro de la taza?" (las penetraciones siempre se verifican)
• "El cargador está asentado en el fotograma 40", "la caja descansa plana", "el arma se mantiene en la mano", "el pie plantado no se desliza" (estructural: seat, rest, hold, distance)
• "El codo nunca se dobla hacia atrás", "la tapa se abre 0-110 grados", "la palma mira hacia la mesa" (rotacional: range, align)

No es para: corregir poses, física o equilibrio, contacto de boca o tela, superposición malla contra malla.

Requisitos

Blender (cualquier versión reciente; usa su propio Python internamente) y la biblioteca estándar de Python 3 para el script anfitrión. Blender se encuentra desde --blender RUTA, luego $BLENDER, luego en PATH, luego en las carpetas de instalación habituales.

Comandos

Todos a través de scripts/dots.py en esta carpeta del skill:

python scripts/dots.py selftest [--out DIR]       # respuestas conocidas; ejecutar primero en una máquina nueva
python scripts/dots.py bones <archivo.fbx|.blend> # los huesos del rig y el mapa de huesos propuesto
python scripts/dots.py measure <config.json>      # medir, juzgar, escribir dots.json + dots-sheet.png
python scripts/dots.py sheet <dots.json>          # volver a renderizar solo la hoja

Opciones: --blender RUTA, --timeout S (predeterminado 600), --limits finger|limb (medida), --no-sheet (medida, solo números).

La línea de resultado (después de cualquier advertencia o fila de autocomprobación): dots: PASS ... (salida 0), dots: FAIL ... (salida 1) o dots: skipped (<razón>) (salida 2: sin Blender, tiempo de espera agotado, error de Blender o una configuración incorrecta; la razón indica cuál). Una ejecución omitida no es un resultado: corrige la razón y vuelve a ejecutar.

De una frase a una configuración

1. Ejecuta dots.py bones <archivo> para cada archivo de personaje si no estás seguro de la asignación del rig (los nombres de Mixamo y Unity humanoid se asignan automáticamente; de lo contrario, escribe un boneMap).
2. Dale a cada personaje un role corto (her, him, a, b): los puntos son <role>.<punto>.
3. Convierte cada cosa a verificar en una entrada de checks, con los fotogramas en los que debe cumplirse.
4. Nombra una carpeta out (las rutas relativas son relativas al archivo de configuración).

"Su palma derecha sobre su muslo izquierdo en el fotograma 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]}]}

"Su mano derecha sobre su muslo izquierdo" (cualquier parte de la mano): "a": "her.R.hand" (el punto más cercano del grupo cuenta).

Puntos del cuerpo (S = R o L): S.<dedo>.tip, S.<dedo>.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. Grupos: S.hand, S.foot, S.forearm, S.upperarm, S.thigh, S.shin, pelvis.

Superficies (b de un touch): <role> (cuerpo entero), <role>.<hueso canónico> (una parte del cuerpo, ej. him.LeftUpLeg, him.Spine1, him.Head), self, self.<hueso>, prop:<nombre del objeto>, floor, nearest.

Las verificaciones estructurales y rotacionales usan puntos personalizados (en un hueso, un objeto o una región de malla) y direcciones (eje de hueso u objeto, una línea entre puntos, una normal de superficie, una normal de palma, un eje mundial). Configuración completa: references/config.md. Un ejemplo práctico por tipo de verificación: references/checks.md. Una escena completa con touch, hold, align, range y rest (una mano de maniquí agarra y levanta una barra): examples/grab/ en el repositorio ContactDots (config.json; el resultado esperado es PASS 10/10, 0 penetraciones).

Límites: preajuste finger (predeterminado: un contacto puede estar como máximo a 3 mm de distancia en sus fotogramas y como máximo 2 mm dentro en cualquier fotograma) o limb (10 mm / 10 mm), o tus propios números.

Lectura de los resultados

El resumen enumera cada verificación con su número, el peor fotograma, el límite y PASS/FAIL, luego las penetraciones más profundas que el límite. Las distancias son de piel a superficie en mm: positivo = separado, negativo = dentro. Detalles de dots.json: references/results.md.

• Un touch FAIL con una distancia máxima positiva = no está tocando (flotando); con una distancia máxima negativa grande = se está hundiendo.
• skinMm en dots.json es el radio de piel propio de cada punto; un radio extraño significa pesos de skin pobres o una malla corporal incorrecta, y la distancia de ese punto es aproximada.
• Sin verificaciones declaradas: el resumen lista los contactos observados (puntos dentro de 30 mm) en su lugar.

Advertencia sobre el marco mundial

Dos archivos FBX no siempre comparten un mismo marco mundial (diferentes raíces de exportación o compensaciones). Con dos o más personajes, el resumen imprime la posición de la raíz de cada personaje en el primer fotograma. Confirma que están donde deberían, uno respecto al otro, antes de confiar en cualquier número de par. Si no lo están, los números no tienen sentido: corrige la exportación, no ajustes los números.

MIRA la hoja

Los números solos no son suficientes. Abre dots-sheet.png (en la carpeta out) antes de informar: cada malla en un color plano por personaje o accesorio sobre un fondo oscuro, puntos pequeños por personaje, el par medido unido por una línea (amarillo = pasa, magenta = falla; un anillo alrededor de una distancia cercana a cero), un disco translúcido en la superficie tocada (color complementario, contorno y flecha normal), tríadas XYZ (X rojo, Y verde, Z azul claro) en palma, muñeca, cabeza y pelvis en vistas cercanas, flechas para verificaciones de ángulo, un pie de foto por recuadro (id, valor, límite, PASS/FAIL). El par medido, las flechas, el contorno del disco y las tríadas se dibujan delante de las mallas; los puntos pequeños pueden ocultarse detrás de ellas. Verifica que cada recuadro muestre las partes que querías (mano derecha, muslo derecho, fotograma correcto). Un pase en el punto equivocado es una respuesta incorrecta.

Informar

La primera línea del resumen, el número de cada verificación con su límite y fotograma, las penetraciones que superan el límite, las posiciones de la raíz si hay dos personajes, y lo que muestra la hoja. Di que solo midió.