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!
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.
Inspecting the property
outputs of the session init response, we can see both outputs. One of them is called glTFDisplay, the second one Volume.
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
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
Static properties of outputs
The most important static properties of outputs are:
The unique id of the output, which is newly generated every time a model gets uploaded.
The unique id of the output, which stays constant each time a model gets uploaded. The
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.
Name of the output to display instead of
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:
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,
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.
Status code of the computation. Examples:
Status of collecting data from the Grasshopper model after a successful computation. Examples:
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
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:
namethat was given to the component in your Grasshopper model.
contentarray contains URLs to one or more binary glTF files.
They have properties
bbmax, which contain an approximation of the bounding box of the glTF files.
uidof these outputs corresponds to the instance id of the display component in Grasshopper.
Our example shown above contains a single display output called glTFDisplay.
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
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
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.