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 usingnpm
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?