First steps with the API

New viewer version
This article and the other ones in the Viewer category of this website concern the version 2 of the ShapeDiver viewer API. We have since released a version 3 of the viewer API which is documented in the new help center. All the information below is still relevant if you are using version 2 for legacy purposes. Keep in mind that by the end of 2022, maintenance for the version 2 will stop and no more updates or patches will be rolled out to this version. Consider reading our migration guide to version 3.

Once you manage to embed a ShapeDiver model in a web application, the next step is to communicate with this model using the API. The Shapediver API opens the doors to anything from custom User Interfaces to eCommerce and ERP system integrations.

Test model

If you are just testing the API and don't have a model yet, you can embed this model to get the hang of it: https://app.shapediver.com/m/shapediver-api-demo-first-example.
What you need from this page is the "Ticket for direct embedding" in the bottom right section. Keep reading to see how to use it. We'll use this model throughout the documentation, when we give examples of API responses. You can also use the fiddle below to play with the various API functions.

List the model parameters

What makes ShapeDiver models really special is the fact that they come with multiple parameters, allowing to change shapes, sizes, colors and options. As a consequence, the first interaction you'll have with a model will often start with requesting its parameter definitions. It's a bit like asking "How do you do?", except the model will give you a bit more information than "Fine, thank you".

In order to list the parameters, you need to call:

api.parameters.get();

This function returns an object with a single 'data' property, which contains an array of all the parameters available in this model. The test model above contains five of them. Each parameter is described by a set of properties. For example, there is a number parameter, with the name "Couch Length (cm)", that accepts values between 120 and 216. Its default value is 162.

Update a parameter

Let's now try to update the length parameter by calling the updateAsync function:

api.parameters.updateAsync({name: "Couch Length (cm)", value: 210});

You will notice the viewer blurring while the updated geometry is loaded in the viewer from our servers. Like most of the API functions, updateAsync returns a promise when the update is complete, which means you can use it to trigger another piece of code after the update. For example, you might want to replace the camera right in front of your geometry if the update changed the size or the position of the contents of the scene. It goes like this:

api.parameters.updateAsync({name: "Couch Length (cm)", value: 210}).then(
  function(result){
    api.scene.camera.zoomAsync();
  }
);

List the assets in the scene

A ShapeDiver 3D scene contains several types of assets: geometry objects, materials and data created by the model. They can all be listed using the Scene interface:

api.scene.get(null, "CommPlugin_1");

Without going into too much detail here, the first parameter is set to null in order to ask for all the assets, without any filters. The second parameter is the name of the communication plugin used to communicate with our servers. By default, it is always called "CommPlugin_1", but several plugins can exist if several models are loaded in the same scene. The test model contains three pieces of geometry ("Fabric", "Feet" and "Floor") as well as three materials named accordingly (there is one material for each geometry output in this case). There is also one piece of data output, called "NumberOfSeats". If you are looking specifically for the data outputs, you can filter them directly by calling

api.scene.getData();

ShapeDiver models can not only export data but also geometry, images and text files. This is done through the Export interface.

Export files from the viewer

api.exports.get();

 Our test model contains one export asset, called "Download 3D Model". In order to trigger the export, use the requestAsync function. By default, the export is done silently in the background and the promise returns a data object which contains a time-limited download link.

api.exports.requestAsync({name: "Download 3D Model"}).then(
  function(response){ 
    var result= response.data;
    console.log("Sucessfully exported the file " + result.filename + ".")
    let link = result.content[0].href;
    console.log("Use this link to download the file: " + link);
  }
);