OBYOM

A lightweight WebGPU 3D viewer for interactive model previews in the browser.

OBYOM exposes a small TypeScript API for mounting a viewer on an existing canvas, loading an STL model, and controlling its lifecycle. The project source is hosted on GitFlic; the package is prepared for distribution through the public npm registry.

Current capabilities

WebGPU adapter and device initialization
Public OBYOM viewer class
Binary STL loading and GPU geometry upload
Embedded WGSL shaders in the distributable bundle
Automatic model fitting with an initial angled view
Mouse and touch rotation
Two-finger pinch zoom and pan
Wheel zoom on desktop
Mobile gestures without page scrolling over the viewer
Resize-aware rendering with device-pixel-ratio support
start() / load() / destroy() lifecycle
Device-loss and GPU validation diagnostics
Configurable background color and image

The current runtime loads STL assets. The .obyom binary format is specified separately but is not yet supported by the runtime loader.

Requirements

Node.js 20.9+ and npm 10+ for development and package builds
A browser with WebGPU support
A GPU adapter capable of creating a WebGPU device
HTTPS outside localhost

WebGPU availability depends on the browser, operating system, GPU, driver, and hardware-acceleration settings.

Install from npm

The first public release is being prepared as obyom-3d@0.1.0.

After publication:

npm install obyom-3d

The package includes:

an ESM-compatible production bundle;
generated TypeScript declarations;
WGSL shader source embedded in the bundle, so consumers do not need to copy shader files separately.

Quick start

import { OBYOM } from 'obyom-3d';

const viewer = new OBYOM({
  canvas: '#viewer',
  params: {},
});

await viewer.start();
await viewer.load('/assets/model.stl');

A minimal HTML setup:

<canvas id="viewer" width="700" height="700"></canvas>

Call start() before load(). Call destroy() when the viewer is no longer needed or before replacing it with another instance:

viewer.destroy();

canvas accepts either a CSS selector or an HTMLCanvasElement.

Background options

The viewer accepts optional background configuration through params:

const viewer = new OBYOM({
  canvas: '#viewer',
  params: {
    background: {
      color: '#181818',
      image: {
        source: '/assets/background.jpg',
        fit: 'cover',
        position: 'center',
        opacity: 0.8,
      },
    },
  },
});

Supported image sources include a URL string, URL, HTMLImageElement, and ImageBitmap. Supported fitting modes are cover, contain, and stretch.

Interaction

Desktop: drag to rotate, Shift + drag to pan, wheel to zoom
Touch: one-finger drag to rotate, two fingers to zoom and pan
Mobile: the viewer canvas disables native touch scrolling while a gesture is performed

Development

Clone the GitFlic repository:

git clone git@gitflic.ru:3axap777/obyom.git
cd obyom
npm install

Start the development demo:

npm start

Open http://localhost:3001 in a WebGPU-capable browser.

Run the package checks:

npm run typecheck
npm run build
npm run build:types
npm run pack:check

The package build produces:

dist/
├── package/
│   └── index.js
└── types/
    ├── index.d.ts
    └── webgpu/*.d.ts

To inspect the exact files that would be published:

npm pack --dry-run

To test the package locally without publishing it:

npm pack

Then install the generated tarball in a clean demo project:

npm install /path/to/obyom-3d-0.1.0.tgz

WebGPU compatibility

WebGPU availability depends on the browser, operating system, GPU, driver, hardware acceleration, and browser settings. For local development, use localhost. Deployed applications must use HTTPS.

Applications should check navigator.gpu and show a clear fallback message when WebGPU cannot be initialized.

Project structure

.
├── assets/
├── src/
│   ├── index.ts              Public OBYOM API
│   ├── demo.ts               Development demo entry point
│   ├── shaders/webgpu/       WGSL source of truth
│   └── webgpu/               WebGPU renderer and STL loader
├── dist/                     Generated demo and package output
├── package.json              npm metadata and scripts
├── webpack.config.cjs        Development demo build
├── webpack.package.cjs       npm package build
├── tsconfig.publish.json     Declaration build configuration
└── tsconfig.typecheck.json   Typecheck configuration

Diagnostics

The renderer reports device loss, uncaptured WebGPU errors, and validation errors in the render path. When a browser reports an invalid command buffer at queue.submit(), inspect the first WebGPU validation message: the submit error can be a consequence of an earlier resource, bind-group, shader, or render-pass failure.

Check the following when GPUValidationError appears:

pipeline and shader compatibility;
bind-group layout and bindings;
texture and buffer usage flags;
render-target and depth formats;
vertex-buffer stride and attributes;
resource lifetime.

Source repository

GitFlic — 3axap777/obyom

License

MIT