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

Section Inputs and Outputs provides an overview on how to define outputs in Grasshopper.

Watch the outputs chapter of our Youtube Video ShapeDiver Geometry Backend API explained!

Definition of `outputs` on the Geometry Backend API

We consider an example that uses the following output components:

A glTF 2.0 Display component that outputs a colored sphere, and
a direct data output component that outputs the volume of this sphere.

You can view this model here, or upload it yourself.

Outputs.ghx

Inspecting the property outputs of the session init response, we can see both outputs. One of them is called glTFDisplay, the second one Volume.

The outputs property contains the definition of the outputs that the model exposes. For most outputs defined in the outputs property, there is a direct correspondence to a component of the Grasshopper model. Models may define lots of outputs, which provides a simple possibility to structure your data.

For each output the API exposes some static properties, which do not depend on a computation result of the model. These static properties uniquely define the output (like name and id).

The API also exposes dynamic properties for each output, which contain computation results and related data.

Both the static and the dynamic properties are always part of the objects in the outputs property.

Static properties of outputs

The most important static properties of outputs are:

Property	Description
`id`	The unique id of the output, which is newly generated every time a model gets uploaded.
`uid`	The unique id of the output, 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 output as defined by the Grasshopper model. Give unique names to the output components in your Grasshopper model. This will allow you to easily identify them on the API.
`displayname` (optional)	Name of the output to display instead of `name`.
`material` (optional)	Id of the output which contains material definitions to apply to the output.

You can find the definition of all static properties of outputs by searching for “ResponseOutputDefinition” in the API documentation:

Dynamic properties of outputs

The dynamic properties of an output contain the data resulting from a computation of the model for the given parameter values, and related data.

In case parameter values have not been specified when requesting data from the Geometry Backend API, the default parameter values are used for setting the dynamic properties of the outputs. An example for this is the session init request. Even though parameter values are typically not included with a session init request, the response always includes output data.

The most important dynamic properties of outputs are:

Property	Description
`content`	An array that contains the resulting data. The data may be directly embedded, or available via download from one or several URLs. In case there was no data to be collected from the corresponding component in Grasshopper, `content` will be an empty array.
`version`	A unique identifier for the particular version of the output. 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 output. As an example, parameters which are in no way connected to the output component in Grasshopper are not considered.
`delay`	The `delay` property is set in case the computation of the output is still ongoing. It contains the delay in milliseconds after which a so-called output cache request shall be sent to check again for this output version.
`status_computation`	Status code of the computation. Examples: `success` means that the computation succeeded. `timeout` means that the computation 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 computation results were successfully stored in the caching system. `maxcombinedassetsizeexceeded` means that the maximum output size was exceeded, and therefore the resulting data available on the API is not complete.
`msg`	In case the computation was not successful, a message that provides context.

You can find the definition of all dynamic properties of outputs by searching for “ResponseOutput” in the API documentation.

Types of outputs

Display outputs

Every display component in your Grasshopper model results in a separate output on the Geometry Backend API. These display outputs can be identified in the following way:

The name that was given to the component in your Grasshopper model.
Their content array contains URLs to one or more binary glTF files.
They have properties bbmin and bbmax, which contain an approximation of the bounding box of the glTF files.
The uid of these outputs corresponds to the instance id of the display component in Grasshopper.

Our example shown above contains a single display output called glTFDisplay.

Data outputs

Each direct data output component in your model results in a separate output on the API. These data outputs can be identified by the name given to the component in your Grasshopper model. The example shown above contains a single data output called Volume. The actual data, which was read from the component after computation, is available in the content array.

Material outputs

Using a ShapeDiver Display component or an External display component results in two closely related outputs on the Geometry Backend API.

A display output that outputs the display geometry as one or several glTF files, and
a material output that outputs the material definition to be applied to the glTF file.

An example of this can be seen here:

The output with id 54bff453d49877a668c419272d364ecd is a display output which contains a property called material that refers to the output with id 45195ab31ec122345e076098b7709253. The content of the display output contains a URL to a glTF file, and the content of the material output contains a material definition and URLs to texture images. The glTF file may contain embedded material information itself, which takes higher priority than the information available in the material output.

Requesting the computation of outputs

When opening a model on the ShapeDiver platform, the session init request typically does not contain specific parameter values. This means that the outputs of the session init response will contain the output data resulting from a computation using the default parameter values.

A computation for different parameter values is requested using a computation request. You can inspect this in the browser console by filtering network requests for the keyword “output”. An example:

The request payload shows the requested parameter values. Parameter value "0.5" was requested for the parameter with id 3fc04be8-edd6-4e01-9261-7bc145a4081e (the “Radius” parameter of our example model), and value "0x0c44f0ff" was requested for the parameter whose id is 33bd00f7-fb60-4c82-9558-3b5abccf4322 (the “Color” parameter of our example model).

The response to the computation request is very similar to the session init response, except that it only contains the outputs property and excludes parameters and exports.

It is possible to combine a session init request with a computation request. In this case, the request payload of the session init request includes a payload as shown above.

Definition of outputs on the Geometry Backend API