Creador de planos

Blueprint Maker

Genera una lámina de planos terminada (PNG, por defecto 1920x1080) a partir de:

• un modelo 3D -> vistas ortográficas reales con líneas ocultas: una vista grande 3/4 más vistas lateral, superior y frontal con líneas de cota medidas (pipeline 3D), o
• una imagen 2D -> extracción de líneas con contorno silueta, dimensiones de caja delimitadora y llamadas (pipeline 2D).

Ambos pipelines comparten un mismo motor de maquetación (marco, paneles, cuadro de título, ajuste de texto) para que el resultado tenga el mismo aspecto.

Qué puede y qué no puede hacer (díselo al usuario cuando sea relevante)

• Sin archivo, no hay plano. Un objeto descrito solo con palabras no se puede convertir en un dibujo preciso. Pide un modelo 3D o una imagen. No inventes geometría.
• 3D da vistas ortográficas reales; 2D no puede. Una sola foto tiene un punto de vista, por lo que el pipeline 2D produce una vista de línea artística, no frontal/lateral/superior.
• La calidad de la línea depende de la malla/imagen. Las mallas extraídas de juegos con cientos de miles de triángulos dan líneas densas; es una buena base automática, no una calidad de ilustración hecha a mano.
• La escala es desconocida a menos que el usuario la proporcione. Las dimensiones están en unidades del modelo (u) o píxeles (px) a menos que se proporcione un scale_ref (una medida real). Nunca presentes un tamaño del mundo real adivinado como un hecho.
• Fuentes: la representación de texto incluida usa DejaVu (latín, griego, cirílico). El texto CJK/árabe/hebreo no se renderizará correctamente.
• El diseño está hecho para 16:9 (probado en 1920x1080, 2560x1440 y 1920x1200). Otras relaciones de aspecto estiran la maquetación del panel; comprueba la salida.
• Los activos extraídos de juegos/películas son propiedad intelectual de alguien. Está bien para un fondo de pantalla personal; menciona que no se redistribuya.

Paso 0 - Recopilar entradas (pregunta una vez, solo lo que falta)

1. El archivo (modelo o imagen).
2. Nombre del objeto y una descripción - u ofrécete a redactarla. La descripción debe coincidir con lo que realmente hay en el render (míralo primero). Una descripción de un vehículo con ruedas sobre una criatura de cuatro patas destruye la credibilidad de la lámina; si el texto del usuario no coincide con la geometría, dilo y reescríbelo.
3. Resolución de salida y la zona segura superior si es un fondo de pantalla (una barra de escritorio cubre la parte superior). Por defecto top_safe = 76 (el marco comienza 76 px hacia abajo en 1080p, espacio para una barra de ~1 cm en un portátil). Si el usuario da centímetros, convierte: px_por_cm = ancho_pantalla_px / ancho_pantalla_cm (aproximadamente 36 px/cm en un monitor 1080p de 24", aproximadamente 56 px/cm en un portátil de 15.6"). Usa la altura de la barra en px + ~12.
4. Estilo: blueprint (por defecto, azul), graphite (oscuro con líneas naranjas), paper (claro, imprimible).
5. Idioma del texto (por defecto inglés; escribe el texto de la especificación en ese idioma).

No interrogues al usuario: si ya ha dado suficiente, continúa con los valores por defecto y expón tus suposiciones.

Paso 1 - Configuración

pip install trimesh numpy scipy networkx pillow opencv-python-headless matplotlib --break-system-packages -q
# opcional, solo para mallas > 700k caras: pip install fast-simplification --break-system-packages

Todos los scripts están en scripts/ junto a este archivo. Reemplaza SKILL_DIR con la carpeta del skill.

Paso 2A - Modelo 3D

Inspeccionar (hazlo siempre primero - una imagen, un comando)

python3 SKILL_DIR/scripts/blueprint3d.py inspect MODEL.glb --out /home/claude/insp

Abre inspect.png con view (es una sola hoja de contacto) y lee el texto impreso:

• Fila superior = proyecciones de ejes brutas: determina qué eje bruto es hacia arriba y hacia qué lado mira el objeto.
• Inferior = la vista 3/4 con candidatos de anclaje numerados (amarillo). La consola lista cada cand N con su píxel y posición canónica. La cuadrícula tenue está en píxeles de referencia 1500x860 (utilizable como pick).

Banderas de orientación (marco canónico: +y arriba, frente del objeto hacia -x): --up +Y (por defecto para GLB/glTF; +Z para otros formatos) y --front -X|+X|+Z|-Z|.... La pista impresa nombra el eje horizontal más largo; el frente debe estar a la IZQUIERDA de la vista lateral, así que invierte el signo si la cabeza/frente está en el otro lado. Si la orientación fue incorrecta, vuelve a ejecutar inspect una vez con otros valores. Pon los valores finales en la especificación como "up" y "front".

inspect también toma --az, --el (por defecto 58 / 20) y --k (número de candidatos, por defecto 16). Usa el mismo view az/el en la especificación, de lo contrario los números de los candidatos no coincidirán.

Escribir la especificación

Crea spec.json (esquema a continuación, ejemplo funcional en assets/example_spec_3d.json). Para cada llamada, da un título, una descripción corta y un anclaje:

• "cand": N - un candidato numerado de inspect.png (lo más económico: sin adivinar píxeles). Los candidatos están repartidos por la superficie visible, así que comprueba que el punto realmente cae en la parte que nombras; si ningún candidato está lo suficientemente cerca, usa pick.
• "pick": [px, py] - píxel en la vista de referencia 1500x860 (la cuadrícula en inspect.png)
• "extreme": "+x" | "-x" | "+y" | "-y" | "+z" | "-z" - punto extremo en el marco canónico (el frente es -x; puede estar oculto detrás de la geometría)
• "point": [x, y, z] - coordenadas canónicas exactas

No establezcas "label" a menos que sea necesario: las posiciones de las etiquetas se eligen automáticamente (texto mantenido fuera de la silueta del modelo y de otras etiquetas, columnas ordenadas en los lados del panel, líderes cortos que no se cruzan). "label": [x, y] (coordenadas de referencia 1920x1080, panel principal x 40-1290, y 96-826) fuerza una posición manual y es verificado por la auditoría a continuación.

Construir

python3 SKILL_DIR/scripts/blueprint3d.py build MODEL.glb spec.json --out /mnt/user-data/outputs/blueprint.png

Las vistas pintadas se almacenan en caché en disco (~/.cache/blueprint-maker, o $BP_CACHE), con clave basada en modelo + vista + estilo. Cambiar texto, etiquetas, llamadas o contenido independiente de la paleta reconstruye en unos 2 s en lugar de volver a pintar; --no-cache o "cache": false lo desactiva.

Diseños: "layout": "multi" (por defecto: vista grande 3/4 + lateral/superior/frontal + dimensiones) o "single" (solo la vista 3/4, más ancha).

Bloqueo de especificación (vinculación entre especificación y modelo)

Los anclajes escritos como cand, pick o extreme solo tienen significado para el modelo, la orientación y la vista en los que fueron elegidos. La primera construcción escribe <spec>.lock.json junto a la especificación: el punto 3D al que se resolvió cada anclaje, una huella geométrica del modelo y la configuración que influye en los anclajes (up, front, vista az/el, candidates, max_faces). Cada construcción posterior vuelve a resolver los anclajes y compara:

• anclajes movidos (modelo, orientación o vista diferentes) -> la construcción falla con error: spec is not bound to this model ..., nombrando cada llamada y qué cambió. Vuelve a ejecutar inspect con la configuración de la especificación, vuelve a elegir los anclajes, luego construye con --relock (o restaura el modelo/configuración original);
• el modelo difiere pero cada anclaje aún aterriza en el mismo lugar (por ejemplo, una reexportación sin pérdidas) -> WARNING: binding: ...; comprueba, luego --relock;
• editaste un anclaje a propósito (mismo modelo/configuración) -> la entrada de bloqueo se actualiza silenciosamente.

--no-lock omite la comprobación (no recomendado). Mantén el archivo de bloqueo con la especificación (confírmalo). Nunca "arregles" un error de vinculación ignorándolo: las etiquetas apuntarían a las partes equivocadas.

Paso 2B - Imagen 2D

python3 SKILL_DIR/scripts/blueprint2d.py inspect IMAGE.png --out /home/claude/insp

Lee la cobertura de máscara impresa (la eliminación del fondo funciona para fondos planos o PNGs transparentes; de lo contrario, informa "none"), luego view inspect.png: izquierda = la fuente con una cuadrícula etiquetada en píxeles de origen (para point_px), derecha = lo que ve el extractor de líneas. Las etiquetas de las llamadas también se colocan automáticamente aquí (deja fuera "label").

Escribe spec.json (ver assets/example_spec_2d.json) y construye:

python3 SKILL_DIR/scripts/blueprint2d.py build IMAGE.png spec.json --out /mnt/user-data/outputs/blueprint.png

Ajuste: "detail" 0.3 (limpio, audaz) a 0.8 (recargado); "mode": "edges" (Canny, fotos/renders) o "sketch" (XDoG, arte suave/bajo contraste); "bg": "none" para mantener todo el marco, o "mask": "path.png" para una silueta hecha a mano; "crop": [x0,y0,x1,y1] para aislar el sujeto; "fill" 0-1 para el tinte translúcido del cuerpo.

Paso 3 - Verificar el resultado (no lo saltes, pero mantenlo económico)

El constructor imprime líneas WARNING:. Léelas primero - son una auditoría automática, por lo que normalmente solo necesitas view el PNG una vez, al final:

• error: spec is not bound to this model - ver "Bloqueo de especificación" arriba; esto es un fallo grave, no una advertencia.
• layout: ... - texto de llamada superpuesto al modelo, dos etiquetas superpuestas, un líder cruzando el texto de otra etiqueta / otro líder / su propio texto, texto fuera del panel, texto en la tríada de ejes. Soluciona eliminando el "label" manual (deja que el colocador decida), cambiando el anclaje o acortando el texto.
• description / specs / notes: shrunk to Npx o does NOT fit - acorta el texto o elimina filas en lugar de aceptar texto ilegible.

Luego view el PNG final una vez y verifica lo que la auditoría no puede saber:

1. El modelo está vertical y mirando en la dirección prevista en todas las vistas; las dimensiones son plausibles.
2. Cada punto de llamada realmente aterriza en la parte que nombra su texto.
3. La zona segura superior está vacía (uso como fondo de pantalla).

Si algo está mal, edita la especificación (anclajes, view.az/view.el, longitud del texto, feature_deg) y reconstruye; con la caché esto toma segundos. Total típico: 1 inspección + 1-2 construcciones, 2-3 vistas de imagen.

Paso 4 - Entregar

Guarda en /mnt/user-data/outputs/, llama a present_files, luego responde brevemente. En la respuesta, indica siempre:

• qué textos has inventado (descripciones, especificaciones, observaciones, funciones de llamada) versus lo que se midió del archivo - el usuario debe reemplazar las afirmaciones técnicas inventadas que le importen;
• la suposición de unidades/escala;
• cualquier WARNING o limitación visible (líneas densas, anclaje oculto, relación de aspecto).

Mantener bajo el uso de tokens

• Una imagen de inspect, una view final; confía en la auditoría impresa en lugar de volver a ver después de cada ajuste.
• Usa anclajes cand y deja fuera label; no ajustes manualmente las coordenadas de píxeles.
• Escribe la especificación una vez, completamente (anclajes, textos), luego construye; edita solo los campos que la auditoría o la vista final señalaron.

Escribir el texto de anotación

• Describe solo lo que es visible en los renders; mantén las afirmaciones funcionales plausibles y genéricas. Si el objeto es de una franquicia, no indiques detalles de la tradición de los que no estés seguro.
• Títulos de llamadas: 2-4 palabras. Texto de llamada: una oración corta (alrededor de 70 caracteres). Notas: 3-5 elementos cortos. Descripción: alrededor de 600-700 caracteres. Filas de especificaciones: valor de menos de ~45 caracteres.
• Mantén la redacción técnica y coherente: designación, número de especificación, revisión, unidades.

Referencia de especificación

Claves comunes (ambos pipelines):

clave	significado	por defecto
title	título grande en el cuadro de título	"UNTITLED"
subtitle	línea debajo del título	""
designation	línea en negrita en la parte superior del cuadro de descripción	""
description	párrafo para el cuadro de descripción	(cuadro omitido)
specs	[["Etiqueta","Valor"], ...] para la tabla de especificaciones	(omitido)
notes	lista de cadenas para el cuadro de observaciones (A, B, C...)	(omitido)
notes_title	encabezado de ese cuadro	"DESIGN REMARKS" / "NOTES"
callouts	lista de objetos de llamada (abajo)	ninguno
spec_no, class, rev, sheet, scale	campos del cuadro de título (los que están en blanco se omiten)	sheet "01 / 01", scale "AS SHOWN"
fields	anulación completa de los campos del cuadro de título: [["CLAVE","valor"], ...]	auto
width, height	tamaño de salida en px	1920, 1080
top_safe	y (en 1080p) donde comienza el marco; mantén limpia una barra de escritorio	76
palette	blueprint, graphite, paper	blueprint
scale_ref	`{"axis": "length	height

Solo 3D: up, front, layout (multi/single), view {"az": 58, "el": 20, "margin": 0.045}, candidates (k usado para cand, por defecto 16; debe ser igual a inspect --k), feature_deg (umbral de ángulo de borde, por defecto 38; aumentar a 50-60 para menos líneas), feature_deg_small (por defecto 44, vistas lateral/superior/frontal), max_faces (por defecto 700000), cache (por defecto true).

Solo 2D: mode, detail, bg, mask, crop, fill, fit_subject (recortar al sujeto, por defecto true), view_title, view_sub.

Objeto de llamada: {"title": "...", "desc": "..."} más el anclaje - 3D: cand / pick / extreme / point; 2D: point_px: [x, y] en píxeles de la imagen de origen - y opcionalmente "label": [x, y] para forzar una posición manual.

Solución de problemas

• Modelo girado / al revés / mirando hacia otro lado: vuelve a ejecutar inspect con --up / --front; comprueba la fila superior de inspect.png.
• Solo una mancha gris de líneas: aumenta feature_deg (50-65); para una malla muy densa, también establece max_faces más bajo (necesita fast-simplification).
• Partes faltantes o agujeros transparentes: la malla no es hermética o tiene caras invertidas; el renderizador de algoritmo de pintor lo tolera, pero las partes internas de los activos del juego pueden mostrarse. Reduce view.margin o prueba con un az diferente.
• Muy lento: las mallas de más de ~700k caras se diezman automáticamente si fast-simplification está instalado; de lo contrario, una construcción puede llevar minutos.
• La máscara 2D es incorrecta o fragmentada: el color del sujeto está demasiado cerca del fondo. Usa "bg": "none", un crop, o proporciona un PNG de mask (blanco = sujeto).
• Advertencias de texto: acorta el texto; no reduzcas los tamaños de fuente manualmente.
• Los números de los candidatos no coinciden con la imagen / spec is not bound to this model: el archivo del modelo, up/front, la vista view az/el de la especificación o candidates difieren de aquellos para los que se escribió la especificación. Vuelve a ejecutar inspect con la configuración de la especificación, vuelve a elegir los anclajes, construye con --relock.
• La colocación automática de etiquetas sigue fallando ("no collision-free position"): demasiadas llamadas o demasiado largas para el panel; acorta las descripciones, elimina llamadas o usa "layout": "single" para un panel más ancho.
• Salida de aspecto obsoleto después de editar los scripts: la clave de caché incluye el código del renderizador, pero si tienes dudas, ejecuta una vez con --no-cache.

Archivos

• scripts/binding.py - gestión de archivos de bloqueo de especificación.
• scripts/blueprint3d.py - pipeline de modelo 3D.
• scripts/blueprint2d.py - pipeline de imagen 2D.
• assets/example_spec_3d.json - ejemplo de especificación 3D.
• assets/example_spec_2d.json - ejemplo de especificación 2D.