Create a Design

This guide will walk you through how to create your first programmatic design. We'll utilize a broad spectrum of SDK concepts in this document with the goal of getting you to a full design quickly.

The Core3D SDK is written in TypeScript and ships with type definitions, so using an editor like VSCode will allow you to explore the available methods and resources while editing the code.

You'll need a basic development environment running to make this work. A simple Vite setup is a nice option to get up and running quickly.

Step 1 — Prepare Development Environment
Step 2 — Initialize The SDK
Step 3 — Validate Authentication
Step 4 — Visualize A Design
Step 5 — Breaking It Down
Step 6 — Save The Design

Step 1 — Prepare Development Environment

This is an optional step, feel free to use the development environment of your choice. If you don't have one, Vite is a nice option to get you up and running quickly.

First, install Vite.

npm install --save-dev vite

Then, create an index.html and index.ts in your project root.

touch index.ts
echo '<!DOCTYPE html>
<html>
  <head>
    <title>Core3D SDK</title>
  </head>
  <body>
    <script type="module" src="./index.ts"></script>
  </body>
</html>' > index.html

Finally, boot up Vite. We can start working in index.ts from here.

npx vite

Step 2 — Initialize The SDK

Let's get the SDK initialized and ready to use. We'll provide our API token and initialize the adapter we'll use for rendering, which in this case is the Three.js adapter.

index.ts

1import { Core3D, Material, Model } from '@core3d/sdk';
2import { Adapter } from '@core3d/sdk-adapter-three';
3
4const core3d = new Core3D({
5    apiKey: '...', // your Core3D API token
6    createAdapter: ctx => new Adapter(ctx),
7});

Step 3 — Validate Authentication

Make an API request to ensure your token is working using the core3d.api interface. The core3d.api interface has methods that match the Core3D API endpoints, in this case we're using the Read Auth endpoint.

index.ts

1import { Core3D, Material, Model } from '@core3d/sdk';
2import { Adapter } from '@core3d/sdk-adapter-three';
3
4const core3d = new Core3D({
5    apiKey: '...', // your Core3D API token
6    createAdapter: ctx => new Adapter(ctx),
7});
8
+9const { data: auth } = await core3d.api.auth.me.read();
+10console.log(auth); // { "token": { ... }, "user": { ... } }

Step 4 — Visualize A Design

Now that we're initialized, let's create a new design and render it in the browser. We're giving you the full snippet up front so that you can get a sense of the entire process and we'll break down each part afterwards.

index.ts

1import { Core3D, Material, Model } from '@core3d/sdk';
2import { Adapter } from '@core3d/sdk-adapter-three';
3
4const core3d = new Core3D({
5    apiKey: '...', // your Core3D API token
6    createAdapter: ctx => new Adapter(ctx),
7});
8
-9const { data: auth } = await core3d.api.auth.me.read();
-10console.log(auth); // { "token": { ... }, "user": { ... } }
11
+12const design = core3d.createDesign();
+13const model = await core3d.loadModel(Model.Tee);
+14const cotton = await core3d.loadMaterial(Material.Cotton);
+15
+16design.setModel(model);
+17
+18for (const mesh of design.listMeshes()) {
+19    design.apply(cotton, mesh);
+20}
+21
+22await design.render();
+23
+24const scene = await core3d.loadScene({
+25    layout: 'front',
+26    size: [512, 512],
+27    target: design,
+28});
+29
+30scene.fit();
+31scene.start();
+32
+33document.body.append(scene.element);

Step 5 — Breaking It Down

Let's review the component parts of what we did in the previous step.

We import the Model and Material constants that we'll use to reference public resources in the Core3D API.

import { Core3D, Material, Model } from '@core3d/sdk';

Then we create a new design, and load both a public model and public material for use in the design.

const design = core3d.createDesign();
const model = await core3d.loadModel(Model.Tee);
const cotton = await core3d.loadMaterial(Material.Cotton);

Next, we set the model on the design, then iterate over all available meshes and apply our cotton material to them.

design.setModel(model);

for (const mesh of design.listMeshes()) {
    design.apply(cotton, mesh);
}

We then render the design. The design.render() method will batch render any new or updated elements in the design since the last design.render() call. If the underlying design document has not changed then this method doesn't do anything.

await design.render();

Finally, we load and configure a scene, then append it to document.body so we can see the result. Scene configuration involves a few method calls and parameters.

the layout: 'front' parameter sets the camera position such that we're looking at the "front" of the design
the size: [512, 512] parameter explicitly sets our scene canvas size to 512px by 512px
the target: design parameter sets our design as the primary object in the scene
scene.fit() will ensure the entire design is visible in the scene window
scene.start() will kick off a render loop so you can rotate and zoom the scene (scene.stop() will stop the loop)

const scene = await core3d.loadScene({
    layout: 'front',
    size: [512, 512],
    target: design,
});

scene.fit();
scene.start();

document.body.append(scene.element);

At this point you should see the rendered design in your browser and have the ability to rotate, zoom, etc.

Step 6 — Save The Design

We can export the design document and save it to our Core3D account for later reference, loading, editing, etc. Here's how to do that:

const data = await design.toJSON();
await core3d.api.designs.create({ data, name: 'my new design' });