stl-metrics

Modern, zero-dependency STL metrics for the browser and Node.

Parse a binary or ASCII STL file and get its volume, surface area, bounding box, center of mass, triangle count, and watertightness, plus an optional weight estimate. One small async function that runs the same everywhere: React, Angular, Vue, Node, workers.

Why stl-metrics:

• Runs client-side. Compute a live quote in the browser before uploading anything. No filesystem assumptions.
• Universal input. ArrayBuffer, TypedArray/Buffer, Blob/File, streams, or a file path (Node).
• Zero dependencies. Hand-written parser over typed arrays. Tiny, tree-shakeable, dual ESM + CJS with types.
• Optional worker. Offload big meshes off the main thread with { worker: true } and no bundler configuration: a Blob-URL Worker in browsers, worker_threads in Node.
• Honest about bad meshes. Flags non-watertight / non-manifold / degenerate geometry via isWatertight and warnings[] instead of silently returning a wrong volume.

Install

npm install stl-metrics

Usage

import { parseStl } from 'stl-metrics';

// Browser: straight from a file input.
const metrics = await parseStl(file); // file: File | Blob

// With an off-main-thread worker and a weight estimate.
const withWeight = await parseStl(file, {
  worker: true,
  density: 1.24,     // g/cm^3 (e.g. PLA ~1.24)
  unitScale: 'mm',   // what one model unit means
});

console.log(withWeight);
// {
//   format: 'binary',
//   triangleCount: 12,
//   volume: 1000,                       // raw units^3
//   area: 600,                          // raw units^2
//   boundingBox: { min, max, size },
//   centerOfMass: [x, y, z] | null,
//   isWatertight: true,
//   warnings: [],
//   weight: 1.24,                       // grams
// }

// Node: from a path, a Buffer, or a stream.
import { parseStl } from 'stl-metrics';
const metrics = await parseStl('./model.stl');

Units and weight

STL files store raw, unitless numbers, so all geometry is returned in raw model units. weight is only computed when you tell the library what a unit means:

import { computeWeight } from 'stl-metrics';
const grams = computeWeight(metrics.volume, { density: 1.24, unitScale: 'mm' });

unitScale accepts 'mm' | 'cm' | 'm' | 'in' or a number of millimetres per unit.

API

parseStl(input, options?) => Promise<StlMetrics>

| option | type | default | description | | -------------- | ---------------------------------------- | ------- | ------------------------------------------------------ | | worker | boolean | false | Run off the main thread when a worker is available. | | density | number | - | g/cm^3. With unitScale, adds weight (grams). | | unitScale | 'mm'\|'cm'\|'m'\|'in'\| number | - | What one model unit represents. Required for weight. | | centerOfMass | boolean | true | Compute the solid centroid. | | watertight | boolean | true | Run the manifold / watertight analysis. |

computeWeight(volumeRaw, { density, unitScale }) => number

Estimate mass in grams from a raw volume.

computeMetrics(buffer, coreOptions) => StlMetrics

Synchronous core over an ArrayBuffer, if you have already loaded the bytes and want to avoid the async wrapper.

How volume is computed

The enclosed volume is the absolute value of the sum of signed tetrahedron volumes, one per triangle against the origin. Surface area sums per-triangle cross-product magnitudes, and the center of mass is the volume-weighted centroid of those tetrahedra (only meaningful, and only returned, for a watertight solid).

Performance

Volume, area, bounding box, and center of mass all come from a single linear pass over the triangles and are effectively free. The watertight / manifold analysis is a second pass that deduplicates vertices and counts shared edges, so it is the dominant cost on large meshes.

If you do not need isWatertight, skip it:

// Geometry only, no manifold analysis. Fastest path for large meshes.
const metrics = await parseStl(file, { watertight: false, centerOfMass: false });

With watertight: false the center of mass is reported directly (it is otherwise nulled for meshes that are not closed), so also pass centerOfMass: false if you do not want it. For big files, combine either option with { worker: true } to keep the main thread responsive.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the development workflow, architecture notes, and the release process.

License

MIT