/$$$$$$ /$$ /$$ /$$ /$$$$$ /$$$$$$
/$$__ $$| $$ | $$ /$ | $$ |__ $$ /$$__ $$
| $$ \__/| $$$$$$$ /$$$$$$ /$$$$$$ /$$$$$$ | $$ /$$$| $$ /$$$$$$ /$$ /$$ /$$$$$$$ | $$| $$ \__/
| $$$$$$ | $$__ $$ |____ $$ /$$__ $$ /$$__ $$| $$/$$ $$ $$ |____ $$| $$ | $$ /$$_____/ | $$| $$$$$$
\____ $$| $$ \ $$ /$$$$$$$| $$ \ $$| $$$$$$$$| $$$$_ $$$$ /$$$$$$$| $$ | $$| $$$$$$ /$$ | $$ \____ $$
/$$ \ $$| $$ | $$ /$$__ $$| $$ | $$| $$_____/| $$$/ \ $$$ /$$__ $$| $$ | $$ \____ $$ | $$ | $$ /$$ \ $$
| $$$$$$/| $$ | $$| $$$$$$$| $$$$$$$/| $$$$$$$| $$/ \ $$| $$$$$$$| $$$$$$$ /$$$$$$$//$$| $$$$$$/| $$$$$$/
\______/ |__/ |__/ \_______/| $$____/ \_______/|__/ \__/ \_______/ \____ $$|_______/|__/ \______/ \______/
| $$ /$$ | $$
| $$ | $$$$$$/
|__/ \______/
About
This is a node.js library for interfacing with the ShapeWays 3D printing service. It allows you to:
- Query printers and materials
- Upload 3D models
The package here is basically a thin wrapper for ShapeWays SOAP API. Once you've uploaded models using this library, you can sell them using the client side Add to Cart API.
Example
To use the API, first you connect to ShapeWays using your username and password. Once you have a connection established, you can upload models to the server using this data. That's it!
Here is a trivial example showing how to upload an STL file:
require('shapeways').connect({
username: 'Your Shapeways Username'
, password: 'Your Shapeways Password'
}, function(err, conn) {
conn.upload({
title: 'Test Model'
, model_filename: 'test_model.stl'
})
});
Install
First you need to install node-gyp globally so that you can build required plugins for node-expat:
sudo npm install -g node-gyp
Once that is done, you should be able to just install the package as usual:
npm install shapeways
API
connect(options, callback(err, conn) )
This method connects to ShapeWays. It accepts the following options:
- username : (Required) The username of your account at ShapeWays
- password : (Required) The password of your account at ShapeWays
- application_id : (Optional) An optional string to identify your application
If there was an error connecting, callback will be called with an Error object describing the reason for termination. Otherwise, it will get a second parameter, conn, which is an object tracking the connection to ShapeWays' API.
Connection Object Members
The connection object, conn, created by connect, has the following properties and methods:
printers
The printers property is an array of all currently available 3D printers. Each printer has the following fields:
- title : The name of the printer
- volume : A field representing the total volume it can print
- wallthickness : A lower bound on the wall thickness of any printable object
- technology : A description of the supported printing technology
- x/y/z_bound_min/max : The 3D space of the printer in cm
- materials : An array of supported materials
materials
The materials property is a JSON dictionary of available printing materials, keyed by their name. Each material has the following properties:
- id : The internal id used by ShapeWays to index each material type.
- title : The name of the material
- description : An optional short description of the material
- startup_cost : A fixed cost required to use this material (in USD)
price(options, callback(err, quote )
The price method gets a price quote from ShapeWays for printing a part with a given material and volume. Note that this should be treated as an estimate and may be subject to change (ie it is not legally binding in anyway). options is a dictionary containing the following parameters:
- volume : A nonnegative number representing the volume of the object in cm^3 .
- material : The material to use in the print.
The resulting quote is again a dictionary containing the following parameters:
- price : The price of the object
- includes_tax : A flag which if set determines whether the price includes tax
- includes_shipping : A flag which if set determines whether the price includes shipping
- currency : The currency the price is given in.
upload(options, callback(err, model_id )
The upload method sends a model to ShapeWays. options is a dictionary containing any of the following parameters along with a model and optional texture.
- title : Title of the part. Default: "Unnamed Model"
- desc : A short description of the model. Default: ""
- tags : A comma delimited list of tagged attributes. Default: ""
- view_state : A string describing the view state of the object, must be one of, 'hidden', 'for sale', 'view only' . Default: 'for sale'
- markup : (optional) Mark up in dollars. Default: 0
- units : (optional) The units for the model, must be either 'mm', 'cm', 'm', 'inches' or 'feet'. Default: 'cm'
- scale : (optional) The scale of the model in meters. If present, overrides units. Default: 0.01 (note: same as 'cm' for units)
- materials : (optional) An array of material types. Entries can be either a 1) material_id (numeric values), 2) a string representing the material title (as listed in the materials array), or 3) a reference to a material object. Default: no material restrictions (Note: This feature is not officially supported.)
When upload completes, it calls callback with either an error code, or else a string model_id representing the upload in the ShapeWays database. This model_id can be used with ShapeWays Add To Cart API to sell the model in a store.
Note: It takes some time between when the model is uploaded to ShapeWays and when it appears for sale. Some models may not be printable and must be inspected first. Unfortunately, ShapeWays only notifies of the results of these inspections by email, and so there is for now way to check the status of a part programmatically.
Models
In addition to the above parameters, you also need to specify a model. There are three different ways you can do this:
-
Files
If you already have a copy of your model saved to the file system, you can upload it directly. ShapeWays supports the following file formats:
To upload a file, set model_filename to the path to your model in options.
Note: If you have a VRML part with face colors or a ZIP archive with textures included, then you can additionally set has_color to true in options . The library will try to infer the file type from the extension, though this behavior can be overriden by specifying a model type in the modeltype option. Finally, before upload this library internally converts all formats to a ZIP archive to conserve bandwidth and reduce upload times.
-
Buffers
The buffer interface for uploads is almost identical to the file interface, except that it takes a Buffer object instead of a path to a file. There are only a few slight differences:
- To specify a buffer, set the model_buffer option to the buffer itself.
- You must also specify a modeltype from the above list.
-
JSON
While the above two methods may be sufficient for some purposes, the interchange formats accepted by ShapeWays API are quite cumbersome for applications that process or manipulate 3D geometry in Javascript. To facilitate working with models in Javascript, I added an extra option to directly upload an indexed set of faces using JSON. To do this, you specify an object in the model_json field. For example, here is the option field required to upload a multicolored cube:
conn.upload({ title: 'Test JSON Cube' , units: 'cm' , model_json: { positions: [ [0, 0, 0] , [1, 0, 0] , [0, 1, 0] , [1, 1, 0] , [0, 0, 1] , [1, 0, 1] , [0, 1, 1] , [1, 1, 1] ] , faces: [ [3, 1, 0, 2] , [0, 1, 5, 4] , [6, 2, 0, 4] , [1, 3, 7, 5] , [7, 3, 2, 6] , [4, 5, 7, 6] ] , face_colors: [ [1, 0, 0] , [0, 1, 0] , [0, 0, 1] , [0, 1, 1] , [1, 0, 1] , [1, 1, 0] ] } });model_json may have the following parameters
positions: An array of length 3 arrays describing the vertices of the model.verts: An alternative name forpositionsfaces: An array of arrays of indices describing the faces as counter clockwise oriented polygons.face_colors: (Optional) An array of colors for each face (must be same length asfaces)face_uvs: (Optional) An array of per-face texture coordinates (must be same length as faces ). Overrides face_colors if present along with a texture (see below).vert_uvs: (Optional) An array of per-vertex texture coordinates (must be same length asverts). Overridesface_colorsandface_uvsif present along with a texture (see below).
Note: It is redundant to specify more than one of _face_colors, face_uvs or vert_uvs.
Textures
You can also specify textures to color your models. Note that only VRML and X3D formats support this feature. Currently, the following methods for specifying a texture are supported:
-
Files
To specify a texture as a file, set the option texture_filename to the path of the file.
Note: Only PNG and JPEG are supported. texture_filename must have the correct extension.
-
Buffers
You can also send a buffer containing a PNG or JPEG directly. To do this, set texture_buffer to the buffer of the texture and set texture_type to the type of the texture (either PNG or JPEG).
-
Bitmaps
Finally, for procedurally generated textures there is an interface for uploading raw bitmaps. To do this, you need to specify the following data:
* _texture_bitmap_ : The raw bitmap storing the texture, either a buffer, array or typed array; flattened in row major order starting from the upper left. * _texture_width_ : The width of the texture * _texture_height_ : The height of the texture * _texture_order_ : The pixel order of the texture. Can be 'rgb', 'bgr', 'rgba or 'bgra'. Default: 'rgb'.
Example:
conn.upload({
title: 'Test Bitmap Cube'
, units: 'cm'
, model_json: {
face_uvs: [
[[0,0], [0,1], [1,1], [1,0]]
, [[0,0], [0,1], [1,1], [1,0]]
, [[0,0], [0,1], [1,1], [1,0]]
, [[0,0], [0,1], [1,1], [1,0]]
, [[0,0], [0,1], [1,1], [1,0]]
, [[0,0], [0,1], [1,1], [1,0]]
]
, verts: [
[0, 0, 0]
, [1, 0, 0]
, [0, 1, 0]
, [1, 1, 0]
, [0, 0, 1]
, [1, 0, 1]
, [0, 1, 1]
, [1, 1, 1]
]
, faces: [
[3, 1, 0, 2]
, [0, 1, 5, 4]
, [6, 2, 0, 4]
, [1, 3, 7, 5]
, [7, 3, 2, 6]
, [4, 5, 7, 6]
]
}
, texture_bitmap: [ //Stored in RGB order
255, 0, 0, 0, 255, 0,
0, 0, 0, 0, 0, 255
]
, texture_width: 2
, texture_height: 2
}, function(err, model_id) {
if(err) {
console.log("Failed to upload:", err);
return;
}
console.log("Uploaded model: " + model_id);
});
More Examples
Several examples of the API can be found in the examples/ directory.
Final Notes
This library is still in early development, and ShapeWays' API is currently in flux. It is likely that some of these features may change over time.
Credits
This unofficial wrapper was written by Mikola Lysenko, and is not in any way supported by or affiliated with ShapeWays. This package includes a modified version of node-soap, with patches to work around some API compatibility problems. Additionally, it uses a modified version of Segrgey Korotov's tinyzip, which was extended to handle raw file stream/buffer input. Other than the files in lib/soap-mod and lib/tinyzip-mod, this project is covered by the MIT license. This project has external dependencies on the following npm modules: node-expat, pngjs, underscore.js request
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent