Skip to content

3D preview pipeline

Artist Alley generates several preview artifacts per 3D asset so the viewer has something to show immediately and the browse feed can hover-scrub a turntable. Rendering runs inside the app container: the Go preview job launches a Node worker that drives headless Chromium, so there is no separate render container to deploy.

The renderer is headless Chromium on software WebGL, driven by scripts/threejs/worker.mjs and orchestrated by the Go ModelHandler in app/internal/preview/model.go. No GPU is required.

flowchart LR
  upload[3D asset uploaded] --> probe["preview.3d: stage model + companions"]
  probe --> render["worker.mjs<br/>headless three.js"]
  render --> poster[poster.png]
  render --> frames["turntable/frame_0000..NNNN.png"]
  render --> views["views/top.png<br/>views/bottom.png"]
  poster --> col[col / preview / screen / hires thumbnails]
  frames --> sheet["6×6 sprite sheet + WebVTT cues"]
  sheet --> hover[Browse-feed hover-scrub]

The pipeline previously used a headless Blender container. It was replaced in v0.6.0, with Blender kept as a fallback, and removed from the image entirely in v0.7.0, which halved the server image from 3.64 GB to 1.82 GB.

In the evaluation behind the switch (#497), the replacement rendered roughly 18–24× faster than Blender’s Cycles renderer. It needs no GPU and works on arm64; the Blender path was amd64-only, so arm64 deployments had no 3D previews at all before v0.6.0.

It also loads models through the same code as the interactive viewer: the worker’s page imports the viewer’s own load module (web/src/lib/3d/modelLoader.js) and its default lighting values. That is the property that matters most: the offline render and the in-browser view are meant to agree.

Until v0.8.0 the renderer had its own copy of the load path, and the two drifted: OBJ models and unlit glTF files rendered untextured or flat in thumbnails while the viewer showed them correctly (#689). Sharing the module removed that source of drift.

The worker writes a fixed on-disk layout that the Go side fans out into stored variants:

<output>/poster.png
<output>/turntable/frame_0000.png … frame_{N-1}.png
<output>/views/top.png
<output>/views/bottom.png
ArtifactBecomesNotes
poster.pngcol / preview / screen / hires raster ladder (the default rungs), plus iso/source.pngThe thumbnail you see in the grid.
turntable/frame_NNNN.pngPer-frame variants (turntable/0000.png …)36 frames by default, one every 10°.
Sprite sheetsprites.jpg + sprites.vtt WebVTT cues6×6 grid of 240px cells, a 1440×1440 sheet. Same mechanism as video sprites, so the browse feed scrubs a turntable the way it scrubs a video.
views/top.png, views/bottom.pngReference viewsNot part of the scrub.

Before rendering, the job checks storage for one marker from each group: col, sprites.jpg, turntable/0000.png, views/top.png and iso/source.png. If all five exist, it finishes without rendering. Otherwise the worker renders the full set again in a fresh temporary directory, which is deleted when the job ends.

On an ordinary re-queue, uploads are gated by those group markers too. An existing frame 0 skips all frames; an existing top view skips both reference views. Individual frame and view checks run only when their group’s marker is missing. An existing sprites.jpg skips both the sheet and sprites.vtt; if the JPEG is missing, both are written, even when the VTT already exists. Missing files can therefore stay missing while their representative marker exists. A forced re-render replaces all of them.

Rendered directly by the worker:

ExtensionLoader
glb, gltfGLTFLoader
fbxFBXLoader
objOBJLoader
stlSTLLoader
plyPLYLoader
daeColladaLoader

glb / gltf / fbx / obj are also what the interactive viewer loads. stl / ply / dae are render-only.

Converted first, then rendered: md2, md3, mdl, ms3d, mview are decoded by pure-Go importers that emit .glb, which then takes the normal path above. Of these, only mview opens in the interactive viewer, through Marmoset’s own player.

Not currently rendered: blend, 3ds, x3d, wrl, usd / usda / usdc / usdz, abc. The worker has no loader for these. They upload, download and serve normally but get no generated previews. A converter that would add previews for some of them is planned as an optional add-on (#499); it isn’t available yet.

The extension list in the shared load module (LOADABLE_EXTS in modelLoader.js) is the source of truth; the Go side keeps its own copy, maintained by hand. A smoke test (scripts/threejs/smoke.mjs) runs inside the built image and renders generated fixtures covering every format in that list. It checks that the outputs exist, that the poster isn’t blank, that materials were normalised and, for the textured fixtures, that the textures decoded and the poster has saturated colour. CI runs it against the production image for changes that touch the render chain. It doesn’t compare the Go copy against the list.

3D assets routinely carry siblings: .mtl next to .obj, .bin next to .gltf, separately-uploaded textures. The Go handler stages the model and its companions into the same working directory before rendering, so the loaders find them with no operator configuration.

These are the worker’s flags. The Go handler passes all six, with the same values as the defaults below; they aren’t operator settings.

FlagDefaultNotes
--inputrequiredPath to the source model.
--workdirthe model’s directoryMust contain the model and its companions.
--outputrequiredDirectory root for the artifacts above.
--frames36Turntable frame count. 36 fills the 6×6 sprite grid exactly; with fewer, cells stay empty, and frames past 36 are left off the sheet.
--res512Square render resolution for frames and views.
--poster-res2048Poster resolution.

How many renders run at once is set by the job queue, not by these flags: the jobs.type_concurrency.preview.3d system setting, which is 2 by default.