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.

import { Core3D } from '@core3d/sdk';
import { Adapter } from '@core3d/sdk-adapter-three';

const core3d = new Core3D({
    apiKey: '...', // your Core3D API token
    createAdapter: ctx => new Adapter(ctx),
});

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.

const { data: auth } = await core3d.api.auth.me.read();

console.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.

import { Core3D, Material, Model } from '@core3d/sdk';
import { Adapter } from '@core3d/sdk-adapter-three';

const core3d = new Core3D({
    apiKey: '...', // your Core3D API token
    createAdapter: ctx => new Adapter(ctx),
});

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

design.setModel(model);

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

await design.render();

const scene = await core3d.loadScene({ size: [512, 512] });

scene.setDesign(design);
scene.setLayout('front');
scene.fit();
scene.start();

document.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 a couple of new constants that we'll use to reference public resources in the Core3D API.

import { ..., 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.

scene.setDesign(design) sets our design as the primary object in the scene
scene.setLayout('front') sets the camera position such that we're looking at the "front" of the design
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({ size: [512, 512] });

scene.setDesign(design);
scene.setLayout('front');
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' });