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.
Visión general
Sección titulada «Visión general»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"]
Por qué three.js
Sección titulada «Por qué three.js»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.
Artefactos
Sección titulada «Artefactos»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| Artefacto | Se convierte en | Notas |
|---|---|---|
poster.png | la escala de rásteres col / preview / screen / hires (los peldaños por defecto), más iso/source.png | La miniatura que ves en la cuadrícula. |
turntable/frame_NNNN.png | Variantes por frame (turntable/0000.png …) | 36 frames por defecto, uno cada 10°. |
| Sprite sheet | sprites.jpg + marcas WebVTT sprites.vtt | Cuadrí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.png | Vistas de referencia | No 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.
Formatos admitidos
Sección titulada «Formatos admitidos»Renderizados directamente por el worker:
| Extensión | Cargador |
|---|---|
glb, gltf | GLTFLoader |
fbx | FBXLoader |
obj | OBJLoader |
stl | STLLoader |
ply | PLYLoader |
dae | ColladaLoader |
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.
Archivos complementarios
Sección titulada «Archivos complementarios»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.
Parámetros
Sección titulada «Parámetros»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ón | Valor por defecto | Notas |
|---|---|---|
--input | obligatorio | Ruta del modelo de origen. |
--workdir | el directorio del modelo | Debe contener el modelo y sus complementos. |
--output | obligatorio | Directorio raíz de los artefactos anteriores. |
--frames | 36 | Nú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. |
--res | 512 | Resolución cuadrada del renderizado de frames y vistas. |
--poster-res | 2048 | Resolució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.
Relacionado
Sección titulada «Relacionado»- ADR 0069: la decisión de abandonar Blender.
- Arquitectura: dónde encaja el worker de previsualización.