Getting started

This page will walk you through how to design, display, and animate a basic 3D model with Zdog.

HTML

Zdog is rendered on a <canvas> or <svg> element. Set width and height attributes to set the size.

<canvas class="zdog-canvas" width="240" height="240"></canvas>

Add the Zdog JavaScript file to your page. For quick demos, add the CDN URL. Finally add a <script> for your demo’s JS file.

<script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>
<script src="zdog-demo.js"></script>

Initial static demo

Let’s jump in with a basic non-animated demo.

// zdog-demo.js

// create illo
let illo = new Zdog.Illustration({
  // set canvas with selector
  element: '.zdog-canvas',
});

// add circle
new Zdog.Ellipse({
  addTo: illo,
  diameter: 80,
  stroke: 20,
  color: '#636',
});

// update & render
illo.updateRenderGraph();

Let’s break it down. The Zdog API mostly consists by creating instances of Zdog’s classes.

Illustration is the top-level class that handles dealing with the <canvas> or <svg> element, holding all the shapes in the scene, and displaying those shapes in the element. We set the rendering HTML element by setting element to its matching selector '.zdog-canvas'. The Illustration instance is then set as a variable illo.

Ellipse is a shape class. We added it to the scene with addTo: illo. So the circle shape is a child of illo — part of it’s descendant graph. We set other properties for the circle to set its size, shape, and color: diameter: 80, stroke: 20, color: '#636'.

Finally, to display the scene, we call illo.updateRenderGraph() to update all the display properties, then render shapes on to the element.

And we get ... a 80px wide purple circle. Exciting!

Animating

To animate our scene we need to re-render illo every frame.

function animate() {
  // rotate illo each frame
  illo.rotate.y += 0.03;
  illo.updateRenderGraph();
  // animate next frame
  requestAnimationFrame( animate );
}
// start animation
animate();

So we wrap illo.updateRenderGraph() within a requestAnimationFrame loop. Now we can manipulate the scene and see its changes animated. We change the rotation of the scene by incrementally increasing illo.rotate.y.

And now the animated circle is ... kind of lame. It is rotating, but being all alone and sitting in direct center, the visual effect is weak. Let’s add another shape, a Rect, and position the shapes in 3D space.

// circle
new Zdog.Ellipse({
  addTo: illo,
  diameter: 80,
  // position closer
  translate: { z: 40 },
  stroke: 20,
  color: '#636',
});

// square
new Zdog.Rect({
  addTo: illo,
  width: 80,
  height: 80,
  // position further back
  translate: { z: -40 },
  stroke: 12,
  color: '#E62',
  fill: true,
});

Now we're cooking. The shapes are positioned by setting translate. The circle has translate: { z: 40 }, so its original position is moved 40 pixels closer up front. The square is 40 pixels further back. The shapes are separated from another so, when rotating, they orbit around the center.

Zoom

Zdog requires setting lots of numbers. I like to keep my numbers smaller. Setting zoom will scale the whole scene proportionally.

let illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  // zoom up 4x
  zoom: 4,
});

new Zdog.Ellipse({
  diameter: 20,
  translate: { z: 10 },
  stroke: 5,
  ...
});

new Zdog.Rect({
  width: 20,
  height: 20,
  translate: { z: -10 },
  stroke: 3,
  ...
});

Drag rotate

Enable rotation with dragging by setting dragRotate: true on the Illustration.

let illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  zoom: 4,
  // enable rotating scene with dragging
  dragRotate: true,
});

We can add back the regular rotation and stop it for dragging with onDragStart.

// rotating flag variable
let isSpinning = true;

let illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  zoom: 4,
  dragRotate: true,
  // stop rotation when dragging starts
  onDragStart: function() {
    isSpinning = false;
  },
});

// add shapes...

function animate() {
  // rotate
  if ( isSpinning ) {
    illo.rotate.y += 0.03;
  }
  illo.updateRenderGraph();
  requestAnimationFrame( animate );
}
animate();

That covers the basics of displaying a 3D model with Zdog. Now you’re ready to learn more about Zdog modeling and shapes.