Learn to Design and Animate in 3D with Zdog

There’s a cool JavaScript library that names like Chris Gannon, Val Head, and CodePen are all raving about. You can also find it on Product Hunt, where it’s been doing rather well. The library is none other than Dave DeSandro‘s Zdog.

In this article, I’m going to introduce you to Zdog and show you some cute demos made by amazing devs that you can reverse-engineer and learn from.

Let’s dive in!

What Is Zdog

DeSandro explains what Zdog is about on the library’s dedicated website:

Zdog is a 3D JavaScript engine for <canvas> and SVG. With Zdog, you can design and render simple 3D models on the Web. Zdog is a pseudo-3D engine. Its geometries exist in 3D space, but are rendered as flat shapes. This makes Zdog special.

In other words, you can design, display and animate SVG or <canvas>-based 3D models.

Zdog is small (2,100 lines of code for the entire library, 28KB minified) and developer-friendly (you can quickly implement it using its straightforward, declarative API).

Getting Started with Zdog

As is the case with most JavaScript libraries, you can include Zdog in your project by…

• simply downloading a copy of the library into your local environment from this link: https://unpkg.com/zdog@1/dist/zdog.dist.min.js (https://unpkg.com/zdog@1/dist/zdog.dist.js for the unminified version);
• fetching the library from a CDN: https://unpkg.com/zdog@1/dist/zdog.dist.min.js
• or by typing npm install zdog if you’re using npm

Here’s the official Hello World demo on CodePen to get you up and running with the library right away:

See the Pen Zdog – hello world canvas by Dave DeSandro (@desandro) on CodePen.

DeSandro offers an awesome Getting Started guide, which I will use to give you an idea of how the library works and which results you can expect from it.

How Zdog Works

Let’s begin by creating a static SVG circle.

The HTML is just an SVG element you can use as a wrapper. If you prefer creating your Zdog graphic using the canvas element instead, simply replace the svg tag with the canvas tag:

    <svg id="circle" width="100" height="100"></svg>

Now a sprinkle of CSS on the SVG element:

    #circle {
      background-color: #081d3f;
      width: 100vw;
      height: 100vh;
    } 

Finally, the JavaScript:

    /* create an instance of the Zdog 
    Illustration class */
    let circle = new Zdog.Illustration({
      element: '#circle'
    })

    /* create an instance of the 
    Zdog shape class Ellipse */
    new Zdog.Ellipse({
      // add the shape to the circle
      addTo: circle,
      // set more properties
      diameter: 20,
      stroke: 20,
      color: '#ccc'
    })

    // display the scene
    circle.updateRenderGraph()

To draw graphics, you need to create instances of Zdog classes. Illustration is the top-level class that deals with the <canvas> or <svg> element. The shapes that you create for your scene will be children of the Illustration class instance.

Ellipse is a shape class. You create a new instance of the Ellipse shape class and add it to your container, circle in this case, using the addTo() method. Zdog offers lots of predefined shapes like rect, polygon, and more. To create your custom shape, use the Shape class and define its path points. You can add other properties to your shape like diameter, stroke, and color. For more properties, check out Zdog’s API for the Shape class.

To render your graphic on the screen, call the updateRenderGraph() method on your circle instance.

Here’s what your circle should look like:

See the Pen Zdog Static CircleExample by Maria Antonietta Perna (@antonietta) on CodePen.

Animating and Dragging with Zdog

Animation requires that your circle instance be re-rendered on every frame. For this, you use .requestAnimationFrame() like this:

    function animate() {
      /* incrementally increase 
      the rotation on the y axis */
      circle.rotate.y += 0.03
      // re-render the graphic
      circle.updateRenderGraph()
      // animate the next frame        
      requestAnimationFrame(animate)
    }

    animate()

Zdog quickly lets you add dragging functionality to your graphic. Here’s what you need to do if you’d like to stop the animation when dragging is starting and resume the animation once the dragging is over.

First, set a isSpinning flag to true:

    let isSpinning = true

Next, go back to your circle instance of the Illustration class and set the dragRotate property to true. Further, switch the flag inside the onDragStart() and onDragEnd() methods, so that when the dragging starts the flag is set to false, and when the dragging ends it gets set back to true:

    let circle = new Zdog.Illustration({
      element: '#circle',
      dragRotate: true,
      onDragStart() {
        isSpinning = false
      },
      onDragEnd() {
        isSpinning = true
      }
    })

Finally, adjust the animate() function by adding this conditional statement at the top, so that the rotation takes place only if the isSpinning flag is set to true:

    if(isSpinning) {
      circle.rotate.y += 0.03 
    }

Here’s the working demo, check it out:

See the Pen Zdog Animation and Dragging Example by Maria Antonietta Perna (@antonietta) on CodePen.

Resources and Demos

This is only the tip of the iceberg of all the amazing graphics and animations you can create with Zdog. You can also mix and match it with other libraries like GreenSock for even more stunning results.

Here’s a bunch of resources and demo collections where you can find out more about this latest addition to the design and animation space done in code:

• Zdog website, where you’ll find all the details about the API, more demos, walkthroughs, and more
• Holy Zdog, a CodePen blog entry crammed with Zdog-based demos
• Made with Zdog, a CodePen collection of Zdog-based demos
• Made with Zdog, a Twitter collection of awesome demos, all obviously made with … Zdog

Where are your Zdog creations? Lots of places out there to show them off, don’t you think?

Frequently Asked Questions (FAQs) about Zdog