Exports on the API
Please read section How to inspect the API first. This will explain to you how to inspect the session init response, which is important to understand the following explanations.
The following sections provide an overview on how to define exports using the ShapeDiver plugin for Grasshopper: Download Export, Email Export
Watch the exports chapter of our Youtube Video ShapeDiver Geometry Backend API explained!
Definition of exports on the Geometry Backend API
We consider an example that uses a single Download Export component:
You can view this model here, or upload it yourself:
The definition of the download export looks like this when inspecting the session init response:
The exports property contains the definition of the exports that the model exposes. There is a direct correspondence between each export on the API and a component of the Grasshopper model. Models can define any number of exports.
For each export the API exposes some static properties, which do not depend on a computation result of the model. These static properties uniquely define the export (like name and id).
The API also exposes dynamic properties for each export, which contain computation results and related data. The dynamic properties are only included in reply to an export request.
Static properties of exports
The most important static properties of exports are:
Property | Description |
|---|---|
| The unique id of the export, which is newly generated every time a model gets uploaded. |
| The unique id of the export, which stays constant each time a model gets uploaded. The |
| Name of the export as defined by the Grasshopper model. Give unique names to the export components in your Grasshopper model. This will allow you to easily identify them on the API. |
| Type of the export, currently supported types are |
| Name of the export to display instead of |
You can find the definition of all static properties of export by searching for “ResponseExportDefinition” in the API documentation:
Requesting exports
The computation of an export is requested using an export request. You can easily inspect this in the console of your browser by filtering network requests for the keyword “export”. An example, taken from the model shown above:
The request payload shows the id of the requested export (the id 68a982db7f80342c0911d176f65ffd1b of the export named “Download STL“ of our example model), and it also contains the parameter values for which the export is requested. The response to this export request now also contains the dynamic properties of the export:
Dynamic properties of exports
The dynamic properties of an export contain the data resulting from a computation of the model for the given parameter values, and related data.
The most important dynamic properties of exports are:
Property | Description |
|---|---|
(for exports of type | An array that contains the resulting data, for exports of type In the future we might add support to export several files from a single component in Grasshopper. This will result in several download URLs. |
(for exports of type | The suggest filename to use when downloading the file. This filename is also used to set a Content-Disposition header when downloading the file from the URL specified as part of |
(for exports of type | An object that contains feedback to display to the user, for exports of type |
| A unique identifier for the particular version of the export. This is a hash code which is based on the parameter values that were used to compute the resulting data. The hash code only depends on the values of the parameters which may theoretically influence the results of the export. As an example, parameters which are in no way connected to the export component in Grasshopper are not considered. |
| The |
| Status code of the computation. Examples:
|
| Status of collecting data from the Grasshopper model after a successful computation. Examples:
|
| In case the export was not successful, a message that provides context. As an example, in case there was no data to be exported this message will say |
You can find the definition of all dynamic properties of export by searching for “ResponseExport” in the API documentation.
Types of exports
Exports for download
Related reading: Download Export, Export Options
Please see the example and detailed explanation above. You can give it a try here. Please also see section Lifetime of export download links.
Exports for emailing
Related reading: Email Export , Export Options
This example uses an Email export component:
You can try it out here, or upload this Grasshopper model:
The response to the session init request shows the following definition for the email export:
When requesting an export of type email, the response does not contain a content property but a property called result instead which includes a message msg:
The email being sent contains a download link to the exported file:
In case there was no data to be exported, the property result.msg will notify about this (Sorry, there is no data to be exported for these parameter settings.):
Lifetime of export download links
Type of export | Download link lifetime |
|---|---|
Exports for download | Lifetime of the session, see Sessions and their lifetime |
Exports for emailing | 7 days |
The difference between outputs and exports
The main purpose of outputs is to output data for displaying geometry in the viewer (display outputs) and to output further data related to the state of the configuration or the scene being displayed in the viewer (data outputs). Examples of such further data:
data related to the pricing of products for e-Commerce applications
JSON objects storing the state of a configuration
JSON objects defining the state of a user interface
Speed is vital for display geometry, and therefore the implementation of outputs is optimized for speed.
The main purpose of exports is to support the export of data for production using various file formats. Depending on the file format used, the export might be computationally much more intense than saving display geometry. Therefore exports are only computed on request and are billed for separately.