ePlease 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:

Exports.ghx

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

id

The unique id of the export, which is newly generated every time a model gets uploaded.

uid

The unique id of the export, which stays constant each time a model gets uploaded. The uid depends on the instance id of the corresponding component in Grasshopper, which means it will change if you replace it.

name

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

Type of the export, currently supported types are "download" and "email".

displayname (optional)

Name of the export to display instead of name.

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

content

(for exports of type "download")

An array that contains the resulting data, for exports of type "download" (see Download Export). The exported file is available via download from a URL. In case there was no data to be exported from the corresponding component in Grasshopper, content will be an empty array, and msg will be set accordingly (see below).

In the future we might add support to export several files from a single component in Grasshopper. This will result in several download URLs.

filename

(for exports of type "download")

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 content.

result

(for exports of type "email")

An object that contains feedback to display to the user, for exports of type "email" (see Email Export). The email being sent contains a download link to the exported file.

version

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.

delay

The delay property is set in case the computation of the export is still ongoing. It contains the delay in milliseconds after which a so-called export cache request shall be sent to check again for this export version.

status_computation

Status code of the computation. Examples:

  • success means that the export succeeded.

  • timeout means that the export was cancelled because it took longer than the maximum allowed computation time.

status_collect

Status of collecting data from the Grasshopper model after a successful computation. Examples:

  • success means that the export results were successfully stored in the caching system.

  • maxcombinedassetsizeexceeded means that the maximum export size was exceeded.

msg

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 Sorry, no data to be exported for these parameter settings.

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.ghx

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:

EmailExport.ghx

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.):

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.