Quick Start: Your First Application

This guide walks you through building a minimal, functional 3D configurator from scratch.

1. The HTML Structure

Before writing any JavaScript, you need a container for the viewer. The viewer will automatically resize to fit its parent container.

HTML

<div id="canvas-container" style="width: 100%; height: 500px;">
  <canvas id="canvas"></canvas>
</div>

2. The Implementation

This script initializes the viewport to render the scene and connects to your ShapeDiver model via a session.

TYPESCRIPT

import { createViewport, createSession } from "@shapediver/viewer";

const initShapeDiver = async () => {
  // create a viewport
  const viewport = await createViewport({
    canvas: document.getElementById("canvas") as HTMLCanvasElement,
    id: "myViewport"
  });

  // create a session
  const session = await createSession({
    ticket: "YOUR_MODEL_TICKET",
    modelViewUrl: "YOUR_MODEL_VIEW_URL",
    id: "mySession"
  });
};

initShapeDiver();

3. Interacting with the Model

Once the session is active, you can manipulate it using the API.

Update a Parameter

ShapeDiver models use Parameters as input channels. You can update these programmatically to trigger a re-computation of the model and update the 3D scene.

Option A: The Shorthand

TYPESCRIPT

// Update one or multiple parameters at once
await session.customize({ 
  "PARAMETER_NAME_1": 1500, 
  "PARAMETER_NAME_2": 2 
});

Option B: The Object Method

TYPESCRIPT

// get a parameter from the session by name
const parameter = session.getParameterByName("PARAMETER_NAME")[0];

// change it's value
parameter.value = 1500;
await session.customize();

Request a File Export

Exports allow users to generate and download computation results, such as geometry (3DM, DXF, DWG, STL, etc), images, data reports and much more.

TYPESCRIPT

// get an export from the session by name
const exportApi = session.getExportByName("EXPORT_NAME")[0];

// request the results of that export
const exportResult = await exportApi.request();
const fileUrl = exportResult.content?.[0].href;
window.open(fileUrl);