Developers
Preliminaries
What is a ShapeDiver model?
ShapeDiver models are created by designers from a specific type of CAD file called Grasshopper definitions. Those files do not only contain 3D geometry but rather a list of parameters and associated logic that create many different geometric variations.
After a Grasshopper definition is uploaded to the ShapeDiver platform, designers can access the parameters and logic of their file directly through a web browser. Our platform creates a user interface around the models and displays the geometric variations when parameters are updated through the interface. You can play with an example ShapeDiver model here.
In many instances, ShapeDiver users are interested in using their models outside the context of the ShapeDiver Platform as part of their web applications. Those applications might want to replace the user interface of the ShapeDiver platform with a different one, use the outputs of the definition to process orders in a webshop, or build more complex workflows. This is where the ShapeDiver development tools get involved.
At the core level, each ShapeDiver model exposes a list of parameters, which can be controlled using our various APIs described below, and a list of outputs that get updated when parameter values are changed. In most cases, integrating a ShapeDiver model in a web application consists of sending parameter values to the model and processing the outputs resulting from these parameter values. Some of our development tools open up more complex applications as well, which we describe below.
In that sense, it is not necessary to understand how a ShapeDiver model works or even to have any knowledge of 3D development to integrate ShapeDiver. The model itself can be seen as a black box whose logic and behavior are defined by the designer uploading the model. In some cases, this logic would be extremely difficult to replicate using traditional web development tools, which is why ShapeDiver allows the creation of very complex 3D web applications by delegating some or all of the complex algorithms to designers.
Development tools
If you want to get started building a web application involving ShapeDiver, it is important to identify which development tools you need. Depending on your application, you will probably use one of ShapeDiver’s APIs or SDKs to control our 3D web viewer, retrieve parametric assets directly from our Geometry Backend or manipulate models and user information on our Platform Backend.
In any of these cases, you will interact with parametric models, or, more specifically, Grasshopper models, that run on our Geometry Backend. And your collaborators will most likely include the designers that create those models.
Depending on which of these tools you are using, different authentication methods are available, which we detail in the sections below.
Integrate the ShapeDiver 3D viewer into a web application
Most frequently, web applications based on ShapeDiver rely on our 3D viewer. The 3D viewer is an easy way to communicate with ShapeDiver models, display the geometry outputs using great-looking materials, and trigger file exports when they exist in the model.
The viewer comes with a high-level TypeScript API which abstracts the complexity of manipulating 3D geometry: no knowledge of WebGL or 3D concepts is required to develop using the viewer API.
In order to integrate a ShapeDiver model using the viewer API, you need a few things:
The account hosting the model needs to have whitelisted the domains where the model needs to be embedded. Both local testing domains as well as production top-level domains can be defined. If you do not have a ShapeDiver account yourself in your team or if you do not have permissions to update those domains yourself, contact the relevant person in your team. This article explains how to whitelist domains for embedding using the viewer API.
The model needs to enable embedding. Once embedding is enabled, the embedding ticket and model view url for this model become available. If you are not the designer creating and uploading files to ShapeDiver, ask the relevant person in your team to provide you this ticket and url. This article explains how to enable embedding and get the ticket and model view url you need to get started with the viewer API.
Once the conditions above are reunited, get started with our viewer documentation and code examples here.
Headless access to ShapeDiver models
There are several cases when you might want to bypass the ShapeDiver viewer and directly communicate with ShapeDiver models stored on our backend. Our geometry backend API lets you do just that by providing a REST API to ShapeDiver models. Here are some example cases for the geometry backend API:
You already have a full-blown application that includes your own 3D web viewer. In that case, you might want to directly retrieve geometry and data that are created by ShapeDiver models and include them in your application. Geometry outputs come as glTF 2.0 assets which can be integrated in most web viewers.
You have integrated the ShapeDiver viewer in an online product configurator or other application, but you only want to export files and complex data at a different time than the viewer session (for example, when a client passes the order from the cart, or even hours or days after the order when you actually process it). In that case, you will want to trigger exports from the ShapeDiver model without instantiating a viewer, possibly even without the context of a frontend client.
You want to use a ShapeDiver model to quickly launch a high number of computation requests and store the results for data analysis or futher processing.
In order to communicate with a ShapeDiver model using the geometry backend API, you need the ticket for backend access associated to that model. This ticket can be obtained by the owner of the model (or an administrator of your team if you are part of one) by enabling backend access for this model and copying the ticket generated when access is enabled. This article explains how to enable backend access and get the ticket and model view url.
Manage models programmatically
Both the viewer API and the geometry backend API described above let you interact with specific ShapeDiver models already stored on the ShapeDiver backend. In a sense, each ShapeDiver model comes with its own API.
ShapeDiver provides another API which gives a higher level overview of the library of models associated with a ShapeDiver account. With the platform backend API, it is possible to list all the models of an account, edit their settings, access the metadata associated to them (description, images, embedding and backend tickets, and in the future even more such as audience and computation analytics).
To some extent, the platform backend API is a progammatic way to take many of the actions that a ShapeDiver user can take by logging in their account and interacting with their models there. The frontend of the ShapeDiver platform makes extensive use of the platform backend API itself.