3D Viewer SDK

Owned by Felix Bauer
Last updated: Mar 07, 2022 by Santiago Balladares
3 min read

Introduction

The 3D Viewer Software Development Kit (SDK) provides a software package which can be used to install the 3D Viewer on your own servers/websites.

Prerequisites

Application Access

The 3D Viewer requires access to the application since it is basically the backend necessary for it to work.

Access to the application can be obtained by:

REST API Connection

The 3D Viewer relies on certain properties that are provided by our REST API, e.g. optimal material wall thickness. Instructions on how to obtain such information can be found in the API documentation. In addition, the upload of 3D files must be done through dedicated endpoints available in our API.

An API token is required in order to work with our API.

The API token can be obtained by:

  • If the application is installed On-Premises, generating the API token

  • If the application is on our dedicated Cloud, requesting the API token from us

Implementation

Frontend Framework

It is highly recommended to use a JavaScript framework for the frontend such as Angular, React, or Vue.js. We support Vue.js natively and have seen that Angular and React had worked in the past.

Additionally, the 3D Viewer can be used without any frontend framework, i.e. plain JavaScript. However, following this approach means losing the advantages of a frontend framework and increased development time and effort.

Bundle .zip File

The 3D Viewer SDK is distributed as a bundle .zip file which will be provided by 3YOURMIND. It contains the software package needed to install the 3D Viewer, as well as additional documentation, a README file and an API_REFERENCE file, with all necessary information for its implementation. The 3D Viewer can be installed with a Software Package Manager, such as Yarn or NPM (see Installation).

Recommended Steps

Setup a Proxy

It is recommended to create a proxy between your backend and the 3YOURMIND application. To achieve that, the URL attribute of the 3D Viewer SDK component must point to your proxy. Then, all requests need to be forwarded from there to the 3YOURMIND application unchanged, assuming that authentication disabled. If authentication is needed, then an authentication API token must be added, in the Authorization header, to every request as described in Authentication.

Provide the Material Information

In order for the 3D Viewer SDK to display the correct printability details, certain information about the material that the 3D part will be printed in is required. This information can be provided in the PARAMETER attribute of the 3D Viewer (see parameter).

Customize the 3D Viewer

Various features of the 3D Viewer can be disabled or enabled by configuring the FEATURES attribute (see features). Moreover, the OPTIONS attribute contains additional options to further configure the 3D Viewer, e.g. certain behavior of the 3D Viewer (see options).

We recommend turning off the `Unit` toggle which allows users to change the unit after the file has been uploaded. If it is required that users be able to dynamically change the unit, then you must make sure to persist the unit selection in your implementation.

Examples

Implementation examples can be provided by 3YOURMIND. The examples show basic usage of the 3D Viewer SDK which is comprised of:

  • Uploading a 3d file

  • Displaying it in the 3D Viewer

Examples are available in the following frontend frameworks, as well as in plain JavaScript.

  • Angular

  • React

  • Vue.js

Requirements are outlined in Prerequisites. Also, see Setup a Proxy.

Use Cases

Using only the 3D Viewer

  1. Install the 3D Viewer using the bundle .zip file (see Installation)

  2. Choose your preferred JavaScript framework and follow the usage instructions (see Usage)

  3. Setup a Proxy (see Setup a Proxy)

  4. Upload a 3d file using the api/v2.0/files/ endpoint and save the uuid returned in the response (see Upload)

  5. Configure the 3D Viewer attributes

    1. Pass the 3d file uuid, returned by the API, to the 3D Viewer (see uuid)

    2. Pass the Proxy url to the 3D Viewer (see url)

    3. Provide the Material Information (see Provide the Material Information)

    4. Customize the 3D Viewer (see Customize the 3D Viewer) [Optional]

  6. Use the 3D Viewer

Using the REST API to get 3D file meta data

  1. Upload a 3d file using the api/v2.0/files/ endpoint and save the uuid returned in the response (see Upload)

  2. Call other endpoints with the uuid returned by the API to get:

    • printability information

    • geometric parameter (volume, area, dimensions, #faces, #shells, convexHullVolume, …)

    • download optimized file

    • download thumbnail

To get more info see the API Documentation - Repair and optimize 3D Models.