osPoly - openscad-poly-tools

A library to manipulate OpenSCAD Polyhedrons

This library is still in development (pre 1.0.0) and may change significantly between minor versions. Once it reaches 1.0.0 all breaking changes will use a major revision number, as dictated by semver.

HTML Convertor

An update to the original STL to OpenSCAD convertor, which eliminate the extra vertices, is included as convert.html. It is also available online at JSFiddle.

As of 0.10.0, the library supports converting STL to OpenSCAD on NodeJS.

Functions

Convert Functions

load(filename)

Load an STL as an object for manipulation, using the stl package.

Returns a Promise.

myModelPromise = osPoly.load('./test.stl');
  
// Promise chaining example
osPoly.load('./example.stl')
  .then(model => osPoly.center(model, 'x'));

format(model, [moduleIndex])

Convert an object into a string equivalent of an OpenSCAD document as a step before saving. Supports an optional index to allow multiple objects to save into a file.

osPoly.format(myModel);

save(filename, model)

Save the object as an OpenSCAD file. Currently supports only a single object.

Returns a Promise.

savePromise = osPoly.save('./example.scad', myModel);

process(stlFile, scadFile)

Import an STL file, simplify it, and export an OpenSCAD document. This provides my most common workflow as a single command.

osPoly.process('./example.stl', './example.scad');
  
// Chaining example
osPoly.process('./example.stl', './example.scad')
  .then(() => console.log('Success'), e => console.log(e));

Simplify Functions

reportDuplicatePercentage(model)

Give the percentage of duplicates in the array of points. No changes are made.

osPoly.reportDuplicatePercentage(myModel);

simplify(model)

Eliminate duplicate points in the model's points array and re-map the indices in the faces to match.

osPoly.simplify(myModel);

Translate Functions

center(model, axis)

Move the center (average of the highest and lowest points) of a model to the origin of the specified axis.

osPoly.center(myModel, 'x')

moveToOrigin(model, axis, [moveTop])

Move the lowest or highest point on an axis to the origin.

osPoly.moveToOrigin(myModel, 'z')

translate(model, vector)

Shift the model along one or more axes.

osPoly.translate(myModel, { x: 10, y: -2, z: 0.25 });

Edit

filterForMatch(model, predicate)

Get only the faces of the model which have points matching the predicate.

NOTE: This is not the same as a Boolean operation in OpenSCAD. Any faces that have points eliminated by the predicate will be removed, not modified.

osPoly.filterForMatch(myModel, (point) => point.x > 0);

removeDeadPoints(model)

Eliminate any dead points and correct the indices of the faces to match.

osPoly.removeDeadPoints(myModel);

Notes

Conventions

Nearly all functions take a model, which is an object with arrays of points and faces.

myModel = {
  points: [],
  faces: [],
};

Where an axis is specified, the library should accept the string 'x', 'y', or 'z'; or their index 0, 1, or 2, respectively.

The original objects passed in are not modified. In some cases, the returned points and faces may reference the same original arrays.

Compatibility

This library is developed on Node 9.x, and is tested against 8.x. It uses functionality not available on previous releases. If you would like to use it with an earlier version of NodeJS, please open an issue on GitHub.

Motivation

After importing an STL into OpenSCAD with Riham's STL to OpenSCAD Convertor on JSFiddle and Thingiverse), I discovered a significant duplication of points. I started working on a way to correct this. Along the way, this library was created.

Goals

• Perform simple, brute-force point de-duplication on polyhedrons.
• Move objects
• Cut parts of an object
• Provide a consistent interface for all functions
• Incorporate an update to Riham's original importer
• Provide a Node-friendly version of the import functionality
• Identify faces sharing points in the same plane and merge them
• Support multiple object loading in Node version
• Update the HTML convertor visuals
• Add tests?
• Provide ES5 version?
• Continue to provide "web" version?
• Support earlier Node versionss?