Ir al contenido

Pipeline de previsualización 3D

Artist Alley genera varios artefactos de previsualización por cada asset 3D para que el visor tenga algo que mostrar de inmediato y el feed de exploración pueda recorrer un turntable al pasar el cursor. El renderizado se ejecuta dentro del contenedor de la aplicación: el trabajo de previsualización en Go lanza un worker de Node que controla un Chromium sin interfaz gráfica, así que no hay ningún contenedor de renderizado aparte que desplegar.

El renderizador es Chromium sin interfaz gráfica con WebGL por software, controlado por scripts/threejs/worker.mjs y orquestado por el ModelHandler de Go en app/internal/preview/model.go. No hace falta GPU.

flowchart LR
  upload["Asset 3D subido"] --> probe["preview.3d: preparación del modelo + archivos complementarios"]
  probe --> render["worker.mjs<br/>three.js sin interfaz"]
  render --> poster[poster.png]
  render --> frames["turntable/frame_0000..NNNN.png"]
  render --> views["views/top.png<br/>views/bottom.png"]
  poster --> col["Miniaturas col / preview / screen / hires"]
  frames --> sheet["Sprite sheet de 6×6 + marcas WebVTT"]
  sheet --> hover["Desplazamiento al pasar el cursor en el feed de exploración"]

Antes, el pipeline usaba un contenedor de Blender sin interfaz gráfica. Se sustituyó en la v0.6.0, conservando Blender como alternativa, y se eliminó por completo de la imagen en la v0.7.0, lo que redujo a la mitad el tamaño de la imagen del servidor, de 3,64 GB a 1,82 GB.

En la evaluación que motivó el cambio (#497), el sustituto renderizó aproximadamente entre 18 y 24 veces más rápido que el renderizador Cycles de Blender. No necesita GPU y funciona en arm64; la ruta de Blender era solo para amd64, así que los despliegues en arm64 no tenían previsualizaciones 3D antes de la v0.6.0.

Además, carga los modelos con el mismo código que el visor interactivo: la página del worker importa el propio módulo de carga del visor (web/src/lib/3d/modelLoader.js) y sus valores de iluminación por defecto. Esa es la propiedad más importante: el renderizado sin conexión y la vista en el navegador deben coincidir.

Hasta la v0.8.0 el renderizador tenía su propia copia de la ruta de carga, y ambas se desviaron: los modelos OBJ y los archivos glTF sin iluminación se renderizaban sin textura o planos en las miniaturas, mientras que el visor los mostraba correctamente (#689). Compartir el módulo eliminó esa fuente de desviación.

El worker escribe una estructura fija en disco que el lado Go reparte en variantes almacenadas:

<output>/poster.png
<output>/turntable/frame_0000.png … frame_{N-1}.png
<output>/views/top.png
<output>/views/bottom.png
ArtefactoSe convierte enNotas
poster.pngla escala de rásteres col / preview / screen / hires (los peldaños por defecto), más iso/source.pngLa miniatura que ves en la cuadrícula.
turntable/frame_NNNN.pngVariantes por frame (turntable/0000.png …)36 frames por defecto, uno cada 10°.
Sprite sheetsprites.jpg + marcas WebVTT sprites.vttCuadrícula de 6×6 celdas de 240px, una hoja de 1440×1440. Es el mismo mecanismo que los sprites de vídeo, así que el feed de exploración recorre un turntable igual que recorre un vídeo.
views/top.png, views/bottom.pngVistas de referenciaNo forman parte del recorrido.

Antes de renderizar, el trabajo comprueba en el almacenamiento un marcador de cada grupo: col, sprites.jpg, turntable/0000.png, views/top.png y iso/source.png. Si existen los cinco, termina sin renderizar. Si no, el worker vuelve a renderizar el conjunto completo en un directorio temporal nuevo, que se elimina cuando termina el trabajo.

En una reencolada normal, las subidas también dependen de esos marcadores de grupo. Si ya existe el frame 0, se omiten todos los frames; si ya existe la vista top, se omiten las dos vistas de referencia. Las comprobaciones individuales de frames y vistas solo se ejecutan cuando falta el marcador de su grupo. Si ya existe sprites.jpg, se omiten tanto la hoja como sprites.vtt; si falta el JPEG, se escriben ambos, incluso si el VTT ya existe. Por tanto, los archivos que faltan pueden seguir faltando mientras exista su marcador representativo. Un nuevo renderizado forzado los sustituye todos.

Renderizados directamente por el worker:

ExtensiónCargador
glb, gltfGLTFLoader
fbxFBXLoader
objOBJLoader
stlSTLLoader
plyPLYLoader
daeColladaLoader

glb / gltf / fbx / obj son también los formatos que carga el visor interactivo. stl / ply / dae solo se renderizan.

Se convierten primero y después se renderizan: md2, md3, mdl, ms3d, mview los decodifican importadores en Go puro que generan un .glb, que luego sigue la ruta normal descrita arriba. De estos, solo mview se abre en el visor interactivo, mediante el reproductor propio de Marmoset.

Actualmente no se renderizan: blend, 3ds, x3d, wrl, usd / usda / usdc / usdz, abc. El worker no tiene cargador para ellos. Se suben, se descargan y se sirven con normalidad, pero no se generan previsualizaciones. Está previsto un conversor que añadiría previsualizaciones para algunos de ellos, como complemento opcional (#499); todavía no está disponible.

La lista de extensiones del módulo de carga compartido (LOADABLE_EXTS en modelLoader.js) es la fuente de verdad; el lado Go mantiene su propia copia, a mano. Una prueba de humo (scripts/threejs/smoke.mjs) se ejecuta dentro de la imagen compilada y renderiza fixtures generados que cubren todos los formatos de esa lista. Comprueba que existen las salidas, que el póster no está en blanco, que los materiales se normalizaron y, en los fixtures con textura, que las texturas se decodificaron y que el póster tiene color saturado. La CI la ejecuta sobre la imagen de producción en los cambios que tocan la cadena de renderizado. No compara la copia de Go con la lista.

Los assets 3D suelen venir con archivos hermanos: un .mtl junto a un .obj, un .bin junto a un .gltf, texturas subidas por separado. El manejador de Go coloca el modelo y sus complementos en el mismo directorio de trabajo antes de renderizar, de modo que los cargadores los encuentran sin que el operador configure nada.

Estas son las opciones del worker. El manejador de Go pasa las seis, con los mismos valores que los predeterminados de abajo; no son ajustes del operador.

OpciónValor por defectoNotas
--inputobligatorioRuta del modelo de origen.
--workdirel directorio del modeloDebe contener el modelo y sus complementos.
--outputobligatorioDirectorio raíz de los artefactos anteriores.
--frames36Número de frames del turntable. 36 llena exactamente la cuadrícula 6×6 del sprite sheet; con menos, las celdas quedan vacías, y los frames a partir del 36 se dejan fuera de la hoja.
--res512Resolución cuadrada del renderizado de frames y vistas.
--poster-res2048Resolución del póster.

Cuántos renderizados se ejecutan a la vez lo determina la cola de trabajos, no estas opciones: es el ajuste del sistema jobs.type_concurrency.preview.3d, que por defecto vale 2.

  • ADR 0069: la decisión de abandonar Blender.
  • Arquitectura: dónde encaja el worker de previsualización.