headless-three 1.0.0

package/README.md

@@ -0,0 +1,171 @@
+# headless-three
+
+Headless Three.js rendering for Node.js, made simple.
+Render 3D scenes to images on the server with no browser required.
+Runs Three.js r162 (the last version with WebGL 1 support) without polluting the global scope.
+
+[![npm version](https://badge.fury.io/js/headless-three.svg)](https://www.npmjs.com/package/headless-three)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+* Three.js r162 running in an isolated VM context
+* No global scope pollution
+* Works with any canvas library ([skia-canvas](https://www.npmjs.com/package/skia-canvas), [canvas](https://www.npmjs.com/package/canvas), [@napi-rs/canvas](https://www.npmjs.com/package/@napi-rs/canvas))
+* Headless WebGL rendering via [gl](https://www.npmjs.com/package/gl)
+* Built-in render function with multi-format output (PNG, JPEG, WebP, etc.) via [sharp](https://www.npmjs.com/package/sharp)
+* Texture loading utility
+* Extensible via `runInContext` for custom loaders
+
+## Install
+
+```bash
+npm install headless-three
+```
+
+You also need a canvas library:
+```bash
+npm install skia-canvas
+# or
+npm install @napi-rs/canvas
+# or
+npm install canvas
+```
+
+## Quick Start
+
+```js
+import { Canvas, Image, ImageData } from "skia-canvas"
+import getTHREE from "headless-three"
+
+const { THREE, render, loadTexture } = await getTHREE({ Canvas, Image, ImageData })
+
+// Create scene
+const scene = new THREE.Scene()
+const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100)
+camera.position.set(0, 0, 5)
+
+// Add a lit cube
+scene.add(new THREE.AmbientLight(0x404040))
+const light = new THREE.DirectionalLight(0xffffff, 1)
+light.position.set(-1, 2, 3)
+scene.add(light)
+
+// Load a texture
+const texture = await loadTexture("path/to/texture.png")
+
+const cube = new THREE.Mesh(
+  new THREE.BoxGeometry(1, 1, 1),
+  new THREE.MeshStandardMaterial({ map: texture })
+)
+scene.add(cube)
+
+// Render to file
+await render({
+  scene,
+  camera,
+  width: 512,
+  height: 512,
+  path: "output.png"
+})
+
+// Or get a PNG buffer
+const buffer = await render({ scene, camera })
+```
+
+## API
+
+### `getTHREE(options)`
+
+Returns a promise that resolves to `{ THREE, render, loadTexture, runInContext }`.
+
+#### Options
+
+| Option | Description |
+|---|---|
+| `Canvas` | Canvas class from your canvas library |
+| `Image` | Image class from your canvas library |
+| `ImageData` | ImageData class from your canvas library |
+
+#### Returns
+
+| Property | Description |
+|---|---|
+| `THREE` | The Three.js library object |
+| `render(options)` | Renders a scene to an image buffer or file |
+| `loadTexture(input)` | Creates a `THREE.CanvasTexture` from a Canvas, Image, ImageData, string path, or Buffer |
+| `runInContext(code)` | Executes JavaScript code inside the VM context |
+
+### `render(options)`
+
+Renders a scene to an image buffer or file. When saving to a file, the format is inferred from the extension unless `format` is specified. Buffer output defaults to PNG.
+
+| Option | Default | Description |
+|---|---|---|
+| `scene` | | The Three.js scene to render |
+| `camera` | | The camera to render from |
+| `width` | `1024` | Output width in pixels |
+| `height` | `1024` | Output height in pixels |
+| `path` | | If provided, saves to this file path. Format is inferred from the extension |
+| `format` | | Output format (`"png"`, `"jpeg"`, `"webp"`, `"avif"`, `"tiff"`, etc.). Overrides extension inference |
+
+```js
+// Save to file (format inferred from extension)
+await render({
+  scene,
+  camera,
+  width: 512,
+  height: 512,
+  path: "output.png"
+})
+
+// Save as JPEG
+await render({ scene, camera, path: "output.jpg" })
+
+// Force format regardless of extension
+await render({ scene, camera, path: "output.img", format: "webp" })
+
+// Get PNG buffer (default)
+const buffer = await render({ scene, camera })
+
+// Get JPEG buffer
+const buffer = await render({ scene, camera, format: "jpeg" })
+```
+
+### `loadTexture(input)`
+
+Creates a `THREE.CanvasTexture` from various input types:
+
+```js
+// From a file path
+const texture = await loadTexture("path/to/image.png")
+
+// From an Image
+const img = new Image()
+img.src = "path/to/image.png"
+const texture = await loadTexture(img)
+
+// From a Canvas
+const texture = await loadTexture(canvas)
+```
+
+### `runInContext(code)`
+
+Executes code inside the same VM context as Three.js. This is useful for loading bundled Three.js addons:
+
+```js
+import fs from "node:fs"
+
+const { THREE, runInContext } = await getTHREE({ ... })
+
+// Load a pre-bundled addon
+runInContext(fs.readFileSync("GLTFLoader.bundle.js", "utf-8"))
+```
+
+## How It Works
+
+headless-three uses Node.js's `vm` module to create an isolated V8 context with polyfilled browser APIs (`document`, `window`, `URL`, etc.). Three.js's CJS build runs inside this sandbox, thinking it's in a browser. The canvas library you provide handles the actual drawing surface and image operations. Rendering uses [gl](https://www.npmjs.com/package/gl) for headless WebGL and [sharp](https://www.npmjs.com/package/sharp) for image encoding.
+
+## License
+
+MIT © [Ewan Howell](https://ewanhowell.com/)

package/index.js

@@ -0,0 +1,164 @@
+import vm from "node:vm"
+import fs from "node:fs"
+import { createRequire } from "node:module"
+import createContext from "gl"
+import sharp from "sharp"
+
+class Blob {
+  constructor(bufs, { type }) {
+    this.buffer = Buffer.concat(bufs.map(e => Buffer.from(e)))
+    this.type = type
+  }
+}
+
+export default async function({ Canvas, Image, ImageData }) {
+  const require = createRequire(import.meta.url)
+  const threePath = require.resolve("three")
+  const document = {
+    createElementNS(_, name) {
+      switch (name) {
+        case "canvas": {
+          const c = new Canvas(1, 1)
+          c.style = {}
+          c.addEventListener = function() {}
+          c.removeEventListener = function() {}
+          return c
+        }
+        case "img": {
+          const img = new Image
+          img.addEventListener = function(eventName, cb) {
+            switch (eventName) {
+              case "load":
+                img.onload = cb
+                break
+              case "error":
+                img.onerror = cb
+                break
+            }
+          }
+          img.removeEventListener = function(eventName) {
+            switch (eventName) {
+              case "load":
+                delete img.onload
+                break
+              case "error":
+                delete img.onerror
+                break
+            }
+          }
+          return img
+        }
+        default: throw new Error(`Unknown tag name: '${name}'`)
+      }
+    }
+  }
+  const window = {
+    document,
+    URL: {
+      createObjectURL: blob => `data:${blob.type};base64,${blob.buffer.toString("base64")}`,
+      revokeObjectURL: () => {}
+    },
+    requestAnimationFrame: cb => setTimeout(cb, 0),
+    cancelAnimationFrame: id => clearTimeout(id)
+  }
+  const threeExports = {}
+  const vmCtx = vm.createContext({
+    module: { exports: threeExports },
+    exports: threeExports,
+    document,
+    window,
+    self: window,
+    OffscreenCanvas: Canvas,
+    Image,
+    ImageData,
+    Blob: Blob,
+    fetch: globalThis.fetch,
+    Request: globalThis.Request,
+    Response: globalThis.Response,
+    Headers: globalThis.Headers,
+    Array,
+    Int8Array,
+    Uint8Array,
+    Uint8ClampedArray,
+    Int16Array,
+    Uint16Array,
+    Int32Array,
+    Uint32Array,
+    Float32Array,
+    Float64Array,
+    BigInt64Array,
+    BigUint64Array,
+    Map,
+    Set,
+    WeakMap,
+    WeakSet,
+    ArrayBuffer,
+    SharedArrayBuffer,
+    DataView,
+    setTimeout,
+    setInterval,
+    clearTimeout,
+    clearInterval,
+    requestAnimationFrame: cb => setTimeout(cb, 0),
+    cancelAnimationFrame: id => clearTimeout(id),
+    console
+  })
+  vm.runInContext(fs.readFileSync(threePath, "utf-8"), vmCtx)
+  const THREE = threeExports
+  return {
+    THREE,
+    runInContext: code => vm.runInContext(code, vmCtx),
+
+    async loadTexture(input) {
+      let tex
+      if (input instanceof Canvas) {
+        tex = new THREE.CanvasTexture(input)
+      } else {
+        let canvas
+        if (input instanceof ImageData) {
+          canvas = new Canvas(input.width, input.height)
+          const ctx = canvas.getContext("2d")
+          ctx.putImageData(input, 0, 0)
+        } else if (input instanceof Image) {
+          canvas = new Canvas(input.width, input.height)
+          const ctx = canvas.getContext("2d")
+          ctx.drawImage(input, 0, 0)
+        } else if (typeof input === "string" || input instanceof Buffer) {
+          const img = await new Promise((resolve, reject) => {
+            const img = new Image()
+            img.onload = () => resolve(img)
+            img.onerror = reject
+            img.src = input
+          })
+          canvas = new Canvas(img.width, img.height)
+          const ctx = canvas.getContext("2d")
+          ctx.drawImage(img, 0, 0)
+        }
+        tex = new THREE.CanvasTexture(canvas)
+      }
+      return tex
+    },
+
+    async render({ scene, camera, width = 1024, height = 1024, path, format }) {
+      const glCtx = createContext(width, height)
+      const renderer = new THREE.WebGLRenderer({ context: glCtx })
+      renderer.setSize(width, height)
+      camera.projectionMatrix.elements[5] *= -1
+      const gl = renderer.getContext()
+      const currentFrontFace = gl.getParameter(gl.FRONT_FACE)
+      gl.frontFace(currentFrontFace === gl.CCW ? gl.CW : gl.CCW)
+      renderer.render(scene, camera)
+      gl.frontFace(currentFrontFace)
+      camera.projectionMatrix.elements[5] *= -1
+      const pixels = new Uint8Array(width * height * 4)
+      glCtx.readPixels(0, 0, width, height, glCtx.RGBA, glCtx.UNSIGNED_BYTE, pixels)
+      renderer.dispose()
+      glCtx.getExtension("STACKGL_destroy_context")?.destroy()
+      let image = sharp(Buffer.from(pixels.buffer), { raw: { width, height, channels: 4 } })
+      if (format) image = image[format]()
+      if (path) return image.toFile(path)
+      if (!format) image = image.png()
+      return image.toBuffer()
+    }
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "headless-three",
+  "version": "1.0.0",
+  "description": "Headless Three.js rendering for Node.js, made simple.",
+  "author": "Ewan Howell <ewanhowell5195> & CCCode",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ewanhowell5195/headless-three.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ewanhowell5195/headless-three/issues"
+  },
+  "scripts": {
+    "test": "node tests/test.js skia-canvas && node tests/test.js canvas && node tests/test.js @napi-rs/canvas",
+    "example": "node examples/cube.js"
+  },
+  "dependencies": {
+    "gl": "^8.1.6",
+    "sharp": "^0.34.5",
+    "three": "0.162.0"
+  },
+  "devDependencies": {
+    "@napi-rs/canvas": "^0.1.97",
+    "canvas": "^3.2.3",
+    "skia-canvas": "^3.0.8"
+  },
+  "keywords": [
+    "three",
+    "threejs",
+    "three.js",
+    "node",
+    "headless",
+    "webgl",
+    "rendering",
+    "3d",
+    "server-side"
+  ]
+}