Tutorial

Your first scene

You will build one small scene in four steps. Each figure below is the scene so far: drag it to turn it, scrub the timeline where there is one, and open Code to see exactly what draws it. The next step adds to the code above it.

1. A box on the ground

A scene holds nodes and a camera. Add a ground lattice, the axes and a box:

The smallest scene

Drag to turn, scroll or pinch to zoom, double click to reset.

Open in playground

import { Scene, axes, box, ground } from 'cseen';

const s = new Scene();
s.add(ground(), axes({ at: [-2.5, -1.5, 0] }));
s.add(box({ at: [0.5, 1, 0], size: 1.5, role: 'accent' }));

at is the point the box stands on, the centre of its base. Everything you add with s.add is drawn together, and the camera frames whatever is there.

2. Add more, and say what it is

Add a second box, label both and join them with an arrow. anchor gives a point on an object that follows it if it moves, so the arrow stays attached:

More than one thing

Drag to turn, scroll or pinch to zoom, double click to reset.

Open in playground

import { Scene, arrow, axes, box, ground, label } from 'cseen';

const s = new Scene();
s.add(ground(), axes({ at: [-4, -2, 0], length: 1.5 }));
const a = s.add(box({ at: [-2, 0, 0], size: 1.2 }));
const b = s.add(box({ at: [1.5, 1, 0], size: 1.5, role: 'accent' }));
s.add(label('input', [-2, 0, 1.7], { anchor: 'middle' }));
s.add(label('result', [1.5, 1, 2.2], { anchor: 'middle' }));
s.add(arrow(a.anchor([0.6, 0, 0.6]), b.anchor([-0.75, 0, 0.75]), { role: 'accent' }));

Labels stay upright whatever the camera does, and role: 'accent' picks the theme’s accent colour. Roles, not colours, are how a scene follows any theme.

3. Make it move

Animations are built from tweens and combined on a timeline. Here the things fade in one after another, the arrow draws, and the result moves:

Make it move

Drag to turn, scroll or pinch to zoom, double click to reset.

Open in playground

import { Scene, Timeline, arrow, axes, box, draw, fadeIn, ground, label, moveBy, stagger } from 'cseen';

const s = new Scene();
s.add(ground(), axes({ at: [-4, -2, 0], length: 1.5 }));
const a = s.add(box({ at: [-2, 0, 0], size: 1.2 }));
const b = s.add(box({ at: [1.5, 1, 0], size: 1.5, role: 'accent' }));
const tag = s.add(label('result', [1.5, 1, 2.2], { anchor: 'middle' }));
const flow = s.add(arrow(a.anchor([0.6, 0, 0.6]), b.anchor([-0.75, 0, 0.75]), { role: 'accent' }));

const tl = new Timeline();
tl.play(stagger(0.25, fadeIn(a), fadeIn(b), fadeIn(tag)));   // one after another
tl.chapter('flow').play(draw(flow, 0.9));                   // a named step you can jump to
tl.chapter('move').play(moveBy(b, [0, 1.5, 0], 1.2));

stagger starts each animation a little after the last, par runs several at once and seq runs them one after another. chapter names a step, so a reader can jump to it.

A timeline is replayed from the start to the requested time, so the picture depends only on the time. That is why you can scrub it, pause it, or draw a single frame. tl.lockFit(s) fixes the framing for the whole timeline so nothing is cropped when things move.

4. Put it on a page

The figure above is just the scene and its timeline. To show it on your own page, mount it on an element:

import { Scene, Timeline, mount } from 'cseen';
import 'cseen/cseen.css';

// the scene and timeline from step 3
const el = document.querySelector('#figure')!;
const player = mount(el, s, { timeline: tl });

mount builds the SVG once and updates only what changed. It pauses when the figure is off screen and respects the reader’s reduced motion setting.

To let the reader turn it, add orbit controls. Drag turns, the wheel and pinch zoom, arrow keys turn, and double click resets:

import { orbit } from 'cseen';

orbit(el.querySelector('svg')!, s, { onChange: () => player.invalidate() });

Use fit: 'sphere' in the scene when you add orbit controls: it frames the bounding sphere, so the object keeps its size however it turns.

Where to go next

Coordinates and cameras explains where things go and how to look at them.
Change this scene in the playground and share it as a link.
Browse the gallery for things to put in your own scene.