Building Graphics with Code: Zdog and JS, a quick overview

There are some amazing JS engines out there designed to make building graphics more accessible. As an amateur visual artist/ growing developer, I would love to learn how to build my own static and animated graphics. After a quick google search, I found Zdog, an easy to use lightweight JS engine that renders 'pseudo' 3D images. My post here is to share with you my initial thoughts on the user-friendliness of engine, a quick guide to get going with it's syntax and features where we code together a sphere and a cube rotating through space, and an overall 'general implementation' idea for when this engine would be appropriate for use.

Wait, backup. What does 'pseudo 3D image' mean?

It means 3D in motion, and 2D when static. The power behind zdog is this: you transmute circles and squares on an x,y,z axis. Meaning, you target what direction you want your shape to grow or shrink. When a screenshot is taken, like in the photo above, the image looks 2D. However, when the animation is spun, you can see the dimensionality behind the object.

So why use zdog?

I am going to go a little out of order and get this out of the way right off the bat: If you want to make a game, this isn't the JS engine for you. It doesn't come with the right elements for a game (such as collision detection). Apparently you can modify it manually, but there are probably better engines out there to do your dirty work. (Actually, you might want to bark up the Python tree for that one...more on that later.)

USE ZDOG IF YOU WANT AN ISOLATED 3D IMAGE WITH SIMPLE ANIMATION CAPACITY.

Imagine you want to spin your company's logo on the Home Page and make it have depth. Or you want your 404 Not Found Page to have a bit of artistic fancy so users aren't AS disappointed if their app fails to load. Zdog can help you do these things, and of course, much more depending on where your imagination can take you.

Here is a sweet animation TienCoffee made. It is a model of a solar system. Just imagine how helpful this would be for 1st graders trying to wrap their heads around how the earth moves around the sun. Or if a coder made a model of a molecule and instead of the flat image in a text book, students can see how it connects by simply spinning the image.

Curious to get started? So am I. Let's do a little Zdog challenge together. Dave DeSandro (the creator of Zdog), made this codepen template for new users to play with. Click on it and let's make some shapes!

We are going to make a cube and sphere rotating around an invisible point space.

Don't worry, you can do this. If you know basic JS, Zdog's API is easy enough to grasp. And the results are so fun. I have been coding in JS for less than a year, and the learning curve here is realistically around a few hours to get a hang of the syntax. (That is not speaking to how long it would take in real life to create a product to deploy, but that is beyond our scope today.) Ok, without further delay, let's get started.

Do you see a purple circle inside of a cream box? Great! Off to a good start. Let's make this circle completely solid, take out the diameter and change the stroke to 12.

new Zdog.Ellipse({
  addTo: illo,
  stroke: 12,
  fill: true,
  color: '#636',
});

Whoops! It is super tiny! No worries, just go up to where we are setting illo and change make a new key/value pair of zoom: 8.

Now, let's take a quick minute to look at what's going on here. Ellipse is a shape class in Zdog. We are adding this ellipse shape (with the defined key value pairs that create it's image) to our page with addTo: illo.

Wait, what is illo?

Back in our codpen file, if we scroll up to the top of the JS file, we will see this:

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

Let's say this out loud together to practice technical communication:

We are declaring a variable illo and setting it equal to a new object (using JS's new operator) calling Zdog's Illustration class and setting canvas with our css selector, '.zdog-canvas'. Zoom will be set to 8.

Great! But what is Illustration?

Illustration is a "high level" class in Zdog api that basically attaches your creation to your HTML element. All of your subsequent shape creations in Zdog will have reference to this Illustration class. This is like our fixed point for all the rotations to circle around.

Moving on to Animation!

Go ahead and copy this code to the bottom of your JS file, right before illo.updateRenderGraph();.

function animate() {
  illo.rotate.x += 0.05;
  illo.updateRenderGraph();
  requestAnimationFrame( animate );
}
animate();

Does your codepen look like this?

Sweet! You should see it spinning too. Well, actually, because we changed its' properties, it will look more like a squishing ball. Study the code for a minute; do you see that we declare it to rotate on the x-axis? What if you changed that to y? Have some fun playing with this.

Let's add another class of Rect (short for rectangle) right below our Ellipse.

new Zdog.Rect({
  addTo: illo,
  width: 8,
  height: 8
  stroke: 12,
  color: '#E62',
  fill: true
});

Right now it should look like a breathing rectangle. Why is that? Where did the ball go? It is still there, it is simply hidden behind the rectangle. We can add translate: { z: -10 }, to the key/values of this Rect object. This will push the shape back on the page (along the z axis) by 10 (whatever 10 is distinguished by in Zdog; I would need to look at their API to really know). Go ahead and add x and y values to translate on the rectangle, and do the same with the ellipse. What happens?

new Zdog.Ellipse({
  addTo: illo,
  stroke: 12,
  color: '#636',
  translate: { x: 5, z:10, y:-5 },
  fill:true
});

new Zdog.Rect({
  addTo: illo,
  width: 8,
  height: 8,
  translate: { x: -5, z:-10, y:5 },
  stroke: 12,
  color: '#E62',
  fill: true
});

See if you can get the circle to land on the rectangle. Manipulating what part of these objects will get that job done? Is there another key we need to add in order to accomplish our task?

Drag and Rotate

Ok, now the fun part. Add this code to your illo variable declaration:
dragRotate: true,

Now, add this above it :
let isSpinning = true;

Now, add a function definition to your illo object: onDragStart: function() {
isSpinning = false;
},

Finally, update your animate function to look like this:

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

Great! Did you break it? I sure did. Let's go through what the entire js file should look like at this point:

let isSpinning = true;

const illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  zoom: 6,  
  dragRotate:true, 
  onDragStart: function() {
    isSpinning = false;
  },
});

new Zdog.Ellipse({
  addTo: illo,
  stroke: 12,
  color: '#636',
  translate: { x: 5, z:10, y:-5 },
  fill:true
});
new Zdog.Rect({
  addTo: illo,
  width: 8,
  height: 8,
  translate: { x: -5, z:-10, y:5 },
  stroke: 12,
  color: '#E62',
  fill: true
});

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

illo.updateRenderGraph();

Awesome! Now you can stop the image, and spin it around using your mouse.

Accomplishment: you know the basics of creating shapes and starting animations, congrats! The next step is going to the website and using the tools we explored here to model images. Doesn't that look fun?

TakeAways

1. Zdog's API uses classes (Illustration, Ellipse, and Rect) to make shapes and fix them to your HTML using .
2. Each class renders an object based on coder's choice of color, size and other mutations.
3. Creating animations is a matter of making functions that call illo.rotate (our fixed point) on a particular axis at a particular speed.

If you are excited about the potentials for Zdog, you can jump right into some projects DeSandro lists on Zdog's website and reverse engineer them to learn the basics. Or, you can go back to the codepen we worked on and try adding another shape, or even making a line (what the heck would that look like?). Have fun and happy coding!