HeadlessRasterizer

Overview

@voltstack/headless-rasterizer is a C++ native Node.js addon that renders GLB (glTF Binary) 3D models to PNG images without a GPU or display server. It uses software rasterization with depth buffering, making it ideal for server-side thumbnail generation and batch rendering.


Package	`@voltstack/headless-rasterizer`
Language	C++17 with Node.js NAPI bindings
Platform	Linux x64
Links	GitHub · npm

Installation

npm install @voltstack/headless-rasterizer

API

`rasterize(glbPath, pngPath, width, height, azDeg, elDeg, options?)`

Renders a GLB file to a PNG image using software rasterization.

function rasterize(
  glbPath: string,
  pngPath: string,
  width: number,
  height: number,
  azDeg: number,
  elDeg: number,
  options?: RasterizeOptions
): boolean

Parameter	Type	Description
`glbPath`	`string`	Path to the input GLB file
`pngPath`	`string`	Path for the output PNG file
`width`	`number`	Image width in pixels
`height`	`number`	Image height in pixels
`azDeg`	`number`	Camera azimuth angle in degrees (horizontal rotation)
`elDeg`	`number`	Camera elevation angle in degrees (vertical pitch)
`options`	`RasterizeOptions`	Optional rendering settings

interface RasterizeOptions {
  // Vertical field of view in degrees (default: 60)
  fov?: number;
  // Camera distance multiplier (default: 1.0)
  distScale?: number;
  // If true, Z-axis points up; otherwise Y-axis (default: true)
  zUp?: boolean;
}

Returns: boolean — true if the render succeeded.

Example

const { rasterize } = require('@voltstack/headless-rasterizer');

rasterize(
  'model.glb',
  'thumbnail.png',
  512, 512,
  45, 30,
  { fov: 60, distScale: 1.2, zUp: true }
);

Supported Input

Triangle meshes with optional vertex colors (RGB or RGBA).
Point clouds with adaptive circular splat rendering based on point density.
Index formats: 16-bit and 32-bit indices.

Rendering Pipeline

GLB parsing — Reads the JSON chunk and binary buffer, extracts vertex positions, colors, and indices.
Bounds computation — Multi-threaded bounding box calculation.
Camera setup — Automatic framing based on model bounds with configurable azimuth, elevation, FOV, and distance.
Rasterization — Triangle rasterization with back-face culling and Z-buffer, or circular splat rendering for point clouds.
Output — RGBA PNG encoding via STB.

Performance

Memory-mapped file I/O for zero-copy GLB reading.
Multi-threaded bounds computation.
32-byte aligned memory for cache efficiency.
Compiled with -O3 -ffast-math -pthread.

HeadlessRasterizer

On this page