File parameters (inputs)

Please read the 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.

These components of the ShapeDiver plugin for Grasshopper allow you to define file parameters: Import Bitmap, Import Geometry, Import Text

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

An example

Let’s consider the following example, which uses an Import Geometry component to import a file from any of the supported CAD file formats, displays the imported geometry, and makes it available as an STL download for 3D printing.

You can view this model on the platform, or upload it yourself:

FileParameters.ghx

bunnies.obj

These parameters are shown on the platform:

The “CAD file” parameter corresponds to the Import Geometry component, while the “CAD file URL” parameter is defined by the Direct Text Input component. A public URL can be set for the “CAD file URL” parameter, which the Import Geometry component downloads and imports a file from, in case no file has been uploaded to the “CAD file” parameter yet. This is why the model shows a bunny by default.

When inspecting the model on the browser console, the session init response shows the following parameters to represent the “CAD file” and the “CAD file URL” parameters:

We can see that the unique id of the "CAD file" parameter is bfe63355-314d-4372-a6e8-498e9c11b82e (this will be important below).

How do File parameters work on the API?

In the following, we are going to focus on the “CAD file” parameter. Please go ahead, and

View the model on the platform,
Open the network tab of the browser console (remove any filter keyword),
Click the “CAD file” parameter on the platform,
Select a file (e.g. the file bunnies.obj contained above),
and inspect the API calls made by the viewer.

You should be able to see the following on the browser console:

In case you used bunnies.obj, you should see two bunnies.

This is what happens on the Geometry Backend API:

API call

Description

Upload request

The viewer sends an upload request to the Geometry Backend, which requests an upload URL for the file. The request body includes the id of the parameter (bfe63355-314d-4372-a6e8-498e9c11b82e), and the size and format (the Content-Type) of the file to be uploaded.

CODE

{
  "bfe63355-314d-4372-a6e8-498e9c11b82e": {
    "size":746007,
    "format":"model/obj"
  }
}

Essentially the upload request asks the following to the Geometry Backend:
May I upload a file of type model/obj whose size is 746007 bytes for use with parameter bfe63355-314d-4372-a6e8-498e9c11b82e? If so, please provide me with a unique id for the file, and an upload URL.

In case of success, the Geometry Backend responds with two pieces of information:

the URL which the file can be uploaded to (property href), and
a unique id for the file

CODE

{
    "version": "2.5.2",
    "asset": {
        "file": {
            "bfe63355-314d-4372-a6e8-498e9c11b82e": {
                "href": "https://sdr7euc1models.s3-accelerate.amazonaws.com/f/9357677f-20a8-43aa-a5c3-45f1072df66d/bfe63355-314d-4372-a6e8-498e9c11b82e/d5fba7ae-617c-4d28-81a3-6cd46c38eba7?Content-Type=model%2Fobj&...",
                "id": "d5fba7ae-617c-4d28-81a3-6cd46c38eba7"
            }
        }
    }
}

File upload

The viewer uploads the selected file to the URL which it received from the Geometry Backend (property href as can be seen above).

Computation request

Finally, the viewer sends a computation request. It uses the unique id of the file which it received (d5fba7ae-617c-4d28-81a3-6cd46c38eba7) as the value of the parameter (bfe63355-314d-4372-a6e8-498e9c11b82e).

CODE

{
  "bfe63355-314d-4372-a6e8-498e9c11b82e":"d5fba7ae-617c-4d28-81a3-6cd46c38eba7",
  "f0f01f56-bd06-48aa-8b65-991fa97e0162":"https://www.dropbox.com/s/4a9msx8anr77cxs/bunny_Zup.obj?dl=1",
  "8dbc77a6-8a9a-4249-a1c6-668e31b9ae03":"0x081fe7ff",
  "a4fd5dec-f66e-4329-8376-def2dd09dc11":"0"
}

Key takeaways

The parameter value to be used for File parameters when submitting computation requests and export requests is the unique id of the file that was uploaded.
In order to upload a new file, an upload request needs to be sent first, which will provide a unique id and an upload URL for the file.
You can reuse uploaded files in order to speed up your application. Say your file is a 20MB file which your Grasshopper model imports data from. Uploading the file takes quite a while, but once it’s uploaded the import of this file into Grasshopper is very fast (which means computations will be fast). You can upload the file once, and reuse its id across many computation and export requests.
Uploaded files are linked to your model and to the parameter they were uploaded for. You can not use file ids for other models or other parameters.