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.
Contents
- 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.tsecho '<!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';34const core3d = new Core3D({5 apiKey: '...', // your Core3D API token6 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';34const core3d = new Core3D({5 apiKey: '...', // your Core3D API token6 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';34const core3d = new Core3D({5 apiKey: '...', // your Core3D API token6 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 windowscene.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' });