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.
Overview
Section titled “Overview”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]
Why three.js
Section titled “Why three.js”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.
Artifacts
Section titled “Artifacts”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| Artifact | Becomes | Notes |
|---|---|---|
poster.png | col / preview / screen / hires raster ladder (the default rungs), plus iso/source.png | The thumbnail you see in the grid. |
turntable/frame_NNNN.png | Per-frame variants (turntable/0000.png …) | 36 frames by default, one every 10°. |
| Sprite sheet | sprites.jpg + sprites.vtt WebVTT cues | 6×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.png | Reference views | Not 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.
Format coverage
Section titled “Format coverage”Rendered directly by the worker:
| Extension | Loader |
|---|---|
glb, gltf | GLTFLoader |
fbx | FBXLoader |
obj | OBJLoader |
stl | STLLoader |
ply | PLYLoader |
dae | ColladaLoader |
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.
Companion files
Section titled “Companion files”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.
| Flag | Default | Notes |
|---|---|---|
--input | required | Path to the source model. |
--workdir | the model’s directory | Must contain the model and its companions. |
--output | required | Directory root for the artifacts above. |
--frames | 36 | Turntable frame count. 36 fills the 6×6 sprite grid exactly; with fewer, cells stay empty, and frames past 36 are left off the sheet. |
--res | 512 | Square render resolution for frames and views. |
--poster-res | 2048 | Poster 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.
Related
Section titled “Related”- ADR 0069: the decision to move off Blender.
- Architecture: where the preview worker sits.