m4bwav/polywright

¿Qué hace polywright?

El centro de operaciones para el trabajo con modelos 3D. Decide cómo se crea un modelo, mantiene cada activo en una carpeta con un manifiesto y verifica cada paso con números e imágenes. Las habilidades hermanas contienen la profundidad.

Script: scripts/pw.py en esta carpeta de habilidad (Python 3.9+, biblioteca estándar, un objeto JSON por comando; scripts/pw_bpy.py es su mitad de Blender, nunca se ejecuta a mano). Ejecute python <esta carpeta>/scripts/pw.py doctor una vez por sesión: encuentra Blender (cualquier SO), las bibliotecas de malla de Python, los laminadores y los hosts de ComfyUI, e informa lo que falta. Lista completa de comandos: references/cli.md.

Paso 1: el brief (pregunte solo lo que no pueda inferir)

• Qué: el objeto o lugar, real o imaginado, y qué tan reconocible debe ser.
• Destinos: uno o más de pw.py check --list (game-roblox, game-unity, game-unreal, web-threejs, ar-usdz, commerce-gltf, print-fdm, print-resin, video-blockout, cad-step). El destino establece el presupuesto.
• Tamaño real en metros (un banco mide 1,8 m de largo; una persona mide de 1,7 a 1,8 m). La escala incorrecta es el error silencioso más común; check --real-size-m lo detecta.
• Entradas: una descripción, fotos, un boceto, medidas, una ubicación en un mapa, una malla existente.
• Fidelidad y presupuesto: bloqueo, listo para el juego, héroe; cuánto tiempo o dinero puede costar un generador alojado.

Andamiaje: pw.py new <dir> --name <Nombre> --kind real|imagined|hybrid --route <ruta> --targets a,b --real-size-m X. Carpeta: refs/ (referencias, cada una registrada como fuente), work/ (.blend, intermediarios), out/ (un entregable por destino), renders/ (hojas de revisión), brief.md, manifest.json. Contrato para otros plugins: references/contract.md.

Paso 2: elija la ruta (la más económica que cumpla con el brief)

Situación	Ruta	Habilidad
Un objeto común; la licencia permite la reutilización	find: Poly Haven, Kenney, Quaternius (CC0), Sketchfab y sitios de impresión (verifique cada licencia)	esta habilidad, references/routes.md
Tiene dimensiones, piezas que encajan, bordes afilados (soporte, caja, edificio, mueble)	code (--route procedural): bpy, build123d/CadQuery/OpenSCAD	polywright-generate, polywright-blender
Un lugar real (parque, calle, campus, terreno)	place: OSM + elevación (pw.py place)	polywright-capture
Un objeto real que pueda fotografiar o escanear	capture: fotogrametría, splats, escáner o modelo a partir de medidas	polywright-capture
Orgánico imaginado o único (estatua, criatura, accesorio)	generate: hoja de referencia, luego imagen a 3D	polywright-references, polywright-generate
Personaje héroe que se deforma	generar o esculpir como base, luego retopología y rigging	polywright-generate, polywright-finish

La mayoría de los buenos resultados combinan rutas: un parque OSM con accesorios héroe generados, una casa construida con código con una estatua generada. Registre la ruta por pieza en el manifiesto.

Paso 3: referencias antes de la geometría

Para cualquier cosa que no se encuentre ya hecha, primero recopile o genere referencias (polywright-references): vistas ortográficas sobre una línea de suelo compartida con una barra de altura, muestras de material, referencias de escala. Las entradas generadas determinan la mayor parte del resultado de imagen a 3D.

Paso 4: construya, luego verifique (cada ruta)

1. Primero un bloqueo a tamaño real: primitivas para silueta y proporción. Corrija la escala aquí; es barato ahora.
2. Números: pw.py inspect <archivo>: triángulos, objetos, tamaño, materiales, texturas, UV, hermeticidad, piezas. Léalo antes y después de cada paso destructivo.
3. Imagen: pw.py render <archivo> --out renders/<paso>: seis vistas y un sheet.png. Lea la hoja, no seis capturas de pantalla. Compárela con las referencias: silueta, proporción, piezas faltantes o flotantes, picos de sombreado, eje incorrecto (recostado), escala incorrecta.
4. Destino: pw.py check <archivo> --target <t> --real-size-m X. Fallo significa arreglar antes de entregar; advertencia significa decirlo en la entrega.
5. Registro: pw.py manifest <dir> --add-output out/<archivo> --target <t> --inspect, cada fuente con --add-source <url> --licence <l> --author <a>, luego --validate.

Planificar, actuar y criticar son pases separados: después de construir, mire la hoja como lo haría un crítico y enumere los defectos antes de declarar que está terminado. Vale la pena hacer dos rondas de corrección de un traceback; más allá de eso, repiense el enfoque. Guarde un .blend numerado por hito (work/<nombre>_v03.blend) para que un trabajo largo pueda reiniciarse desde el disco.

Componer un modelo en una imagen

Cuando un modelo de imagen o video sigue dibujando un accesorio diseñado incorrectamente (un fotograma de storyboard, una referencia de escenario, un póster), tome la composición de la imagen y la forma del modelo:

1. Elija la imagen solo para la composición: dónde están las personas, la luz, el objetivo. Un accesorio sustituto simple está bien.
2. pw.py match model.blend --still pic.png --out work/match.png --anchor-px X,Y --anchor-local=X,Y,Z --aim-px X,Y --aim-local=X,Y,Z --depth M --horizon ROW --hide BOX --mask-add BOX: el ancla del modelo (un agarre) aterriza en la mano, su punto de mira (una punta) en el píxel exacto, renderizado RGBA con la lente y el horizonte de la imagen. Establezca --depth para que su ancho en píxeles coincida con el del sustituto (ancho = f_px x diámetro / profundidad; f_px está en el resultado). --hide oculta la pieza detrás de una mano; --mask-add agrega las manos a la máscara.
3. Lea match_paste.png recortado a 3x: forma, tamaño en el encuadre, puntería. Corrija la profundidad y los píxeles, vuelva a ejecutar (segundos).
4. Mezcle dentro de match_mask.png con una edición de imagen enmascarada de baja reducción de ruido (FLUX.2 Klein o cualquier modelo de inpaint: reducción de ruido 0.3 a 0.5, cfg bajo), luego pegue el resultado de nuevo a través de la máscara para que cada píxel fuera de ella siga siendo el de la imagen. Una edición de imagen completa redibuja todo (color HDR, un accesorio más grande).
5. Verifique a tamaño completo; conserve dos o más semillas.

Las hojas de referencia del accesorio también provienen del modelo (polywright-references, Paso 2b).

Sprites de juego a partir de un modelo

Cuando un modelo de imagen sigue equivocándose con un mecanismo en un sprite de juego (una rueda que no es redonda, una cuchilla en el techo), construya el modelo, renderícelo a través de la cámara del propio juego y deje que el modelo de imagen solo pinte:

1. pw.py spritecam <registry.json> --like <sprite> --out camera.json: la cámara ortográfica ajustada a partir de los diamantes del suelo del juego (L-014). Establezca tile_m en ella a los metros por casilla del modelo.
2. Construya el modelo con un prefijo de pieza por objeto (wheel_, roof_...) en la propiedad de escena sprite_parts, moviendo las piezas bajo un empty de pivote construido en el espacio del pivote, y el movimiento en la propiedad de escena loop.
3. pw.py sprite model.blend --camera camera.json --out renders/L1 --scale 10.6667 (1024 px para un sprite de 96 px): lea al estilo sheet los pases y la belleza a 1x junto a los sprites del juego; --frames N --frame-passes id,pos para una pieza animada, --hide wheel_ para una placa sin ella. Luego verifique el tamaño contra los vecinos del juego antes de pintar: aw.py sprite <belleza a 96> --refs <sprites de la misma clase> falla si la cobertura es inferior a 0.9 de su mediana. El ajuste del diamante establece la escala del suelo, no cuán grande se lee el edificio: agregue primero masa y accesorios (paredes más altas, un cobertizo, un patio), luego aumente px_per_tile y mueva footprint_centre_px para que la caja delimitadora abarque el lienzo como los vecinos (L-016). Mantenga las vigas delgadas fuera de la silueta de un cilindro: un tronco nivelado sobre rieles inclinados se lee como si pasara por encima y por debajo de ellos (L-017).
4. Pinte la belleza con Canny de la arcilla como control (un modelo de imagen con un ControlNet), recórtela con el alfa del render para que el encuadre y groundBase se mantengan exactos, luego verifique la pintura contra los datos de ID y borde en sprite.json.

Ilustraciones de escena a partir de un modelo

Una pantalla de carga, un arte clave o una portada alrededor de un modelo que ya existe (un edificio, una máquina): construya la escena en Blender y deje que el modelo de imagen la pinte, para que el mecanismo y el diseño se mantengan correctos.

1. Construya la escena alrededor del modelo con un prefijo de pieza por objeto en la propiedad de escena scene_parts, ruedas y discos en rings, puntos clave o caminos en scene_points. Bancos, diques y muros a lo largo de un camino son un sweep cada uno (impórtelo de scripts/pw_scene.py en un script pw.py bpy), no una fila de cajas (L-020).
2. pw.py framecam problem.json --out cameras.json: puntos del mundo con cajas de pantalla, puntos mantenidos en el encuadre y fuera de las bandas de texto de la UI, una medida de tamaño para maximizar; imprime las mejores cámaras como preajustes. Tome las bandas del archivo de UI real (su padding y anclas), no de una regla general (L-018).
3. pw.py scene scene.blend --cameras cameras.json --camera framecam_1 --out renders/v1 --size 1280x720 (el tamaño de primer pase del flujo de trabajo de pintura): arcilla, belleza, profundidad, normal, ID, línea y scene.json. Lea arcilla y profundidad primero; deje el rango de profundidad a la medición propia de la escena a menos que un preajuste necesite fijarlo (L-019).
4. Pinte con control (profundidad o línea), luego controle la pintura contra scene.json: bordes de anillos, puntos, colores de ID.

Bloqueos de multitudes y batallas (video AI)

Los modelos de video fallan con las multitudes; Blender no. Deje que Blender coloque al ejército y que el modelo de video pinte el aspecto:

1. pw.py crowd --out work/crowd --action clash --preview (o march, advance, charge, hold; --view, --lens, --move), luego lea work/crowd/sheet.png.
2. Elimine --preview para la toma completa: depth.mp4 (control principal), pose.mp4 (filas delanteras), mask.mp4, clay.mp4, camera.json; 832x480, 81 fotogramas a 16 fps por defecto (Wan).
3. Vuelva a pintar el fotograma 1 de arcilla hasta obtener un fotograma inicial aprobado; conduzca Wan VACE o Wan 2.2 Fun Control con el video de profundidad y ese fotograma. Solicite el vestuario, el color por bando, la luz y la neblina, no el recuento de cabezas.

Detalles y lo que no está probado: references/crowd-blockouts.md. La planificación de tomas es de cinewright.

Dos luchadores: pw.py duel shot.json --preview posa dos maniquíes en sus marcas en el set, a través de la cámara de la toma (examples/duel.json); lea sheet.png, luego elimine --preview para el mp4 de cada control. Más: crowd-blockouts.md, "Dos luchadores".

Un elenco pequeño de figuras o juguetes reales (lados intercambiados, una figura extra, marcas perdidas): mallado cada uno a partir de fotos, corrija el color y las marcas pintadas con pw.py mark, proporcione al modelo de video imágenes pw.py turnaround como referencias y un pw.py lineup (equipos en lados fijos, profundidad y máscara) como su apertura: references/figures-for-video.md.

Sets y accesorios para una toma de película: references/film-and-video.md.

Paso 5: finalización y entrega

La finalización por destino (UVs, LODs, convención de mapas normales, conversión de ejes y unidades, compresión) es polywright-finish; la impresión (sólido hermético, paredes, base, división, 3MF) es polywright-print. Entregue la carpeta al plugin que la usa: páginas three.js (threewright), películas y video (cinewright), lugares de Roblox (roblox-agent), proyectos de Unity (unity-agent), una habilidad específica de impresora o laminador para configuraciones de impresión, una habilidad de imagen para más imágenes. Ellos leen manifest.json y out/.

Mensaje de entrega:

Modelo: <nombre> (<ruta>) -> out/<archivo> para <destino>: <tris> tris, <tamaño> m, <hermético/piezas>
Verificación: <destino> pass|warn (<reglas>)   Revisión: renders/<paso>/sheet.png
Fuentes: <n> con licencias; partes hechas con IA: <cuáles, qué modelo>   Pendiente: <lo que no está hecho>

Reglas

• Tamaño real en metros en Blender y glTF (+Z arriba en Blender, +Y arriba en glTF); milímetros solo en archivos de impresión.
• Nunca afirme que una malla está bien por su nombre de archivo o la palabra de un generador: inspeccione, renderice, verifique.
• Cada entrada descargada o generada obtiene una línea de fuente con su licencia. Las tiendas y los sitios de impresión (Fab, Unity Asset Store, Sketchfab, MakerWorld, Printables, Steam) requieren la divulgación de contenido hecho con IA; el manifiesto lo registra.
• Los puentes de Blender sobre MCP ejecutan Python arbitrario: prefiera pw.py bpy en copias; use una sesión MCP en vivo solo cuando el usuario esté mirando (polywright-blender).
• Los Google Photorealistic 3D Tiles pueden verse, nunca exportarse, almacenarse en caché ni rastrearse (según sus términos).

Mantenimiento

Unidad Evergreen, nivel fast (los generadores y Blender se mueven mensualmente). Acompañantes: RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md con evals/evals.json, MAINTENANCE.md, estado en evergreen.json. Lea evergreen.json en cada uso; si está vencido, haga la tarea, luego actualice (evergreen-refresh). Escriba las lecciones en LEARNINGS.md a medida que ocurran.