Import files in the Shapediver viewer

New viewer version
This article and the other ones in the Viewer category of this website concern the version 2 of the ShapeDiver viewer API. We have since released a version 3 of the viewer API which is documented in the new help center. All the information below is still relevant if you are using version 2 for legacy purposes. Keep in mind that by the end of 2022, maintenance for the version 2 will stop and no more updates or patches will be rolled out to this version. Consider reading our migration guide to version 3.

The ShapeDiver API makes it possible to import files to the viewer that can be read and processed through the parametric 3D model. To this end, the API defines files as just another type of parameters that can be used as input for the parametric models. Uploading a file to the viewer therefore works in a similar way than updating the value of a slider or a dropdown menu.

Example model

You can use this example model to test the functionality. It contains a single file parameter which allows users to upload an image and apply it on a mug. We'll refer to this model in the next sections.

Check if the model contains file parameters

In order to be able to import files into a ShapeDiver model, it needs to contain a parameter with the "File" type. You can directly filter and return such parameters by calling:

api.parameters.get({type:"File"});

 The example model contains one file parameter, with the following definition:

{
  defval: ""
  format: (5) ["image/bmp", "image/gif", "image/jpeg", "image/png", "image/tiff"]
  hidden: false
  id: "aba08d5e-4596-40b8-b8b5-2b8f9171f576"
  max: 10485760
  name: "Mug picture"
  note: "This component is currently inactive.↵"
  order: 2
  plugin: "CommPlugin_1"
  type: "File"
  value: ""
}

The format array contains the allowed MIME types for this parameter. In this case, it allows all the image file formats supported by ShapeDiver.

The max property indicates the maximum allowed file size for this parameter, as defined by the designer. Any file bigger than this size will be rejected by the API.

Check out this article for more details about the other properties of the parameter definition.

Updating a file parameter

File parameters essentially work like other ShapeDiver parameters. They can be updated using the same function:

api.parameters.updateAsync({name: "Mug picture", value: file});

In this case, file needs to be a Javascript File, or at least a more general Blob. Depending on the architecture of the web application, there are several ways to create such files to be passed to the function. In the case of a simple, front-end upload form, they are simply created using <input> DOM elements with the file type.

<input id="image-file" type="file">

We can listen to the onchange event of the input to trigger the parameter update. When manipulating this element in javascript, it contains a files property, which is an array of files selected by the user. In the case of a single file, the first element is the one we want to send to the API.

document.getElementById("image-file").onchange = function(res) {
  let file = document.getElementById("image-file").files[0];
  api.parameters.updateAsync({
    name: "Mug picture",
    value: file
   }).then(
    function(response) {
     alert("File successfully uploaded", response);
    }
  );
};

You can of course add front-end checks regarding the selected file types and sizes, to make sure the API won't reject them.

File import Demo

Find below a fiddle with the complete example discussed in this article.