DEV Community: Duc Phat

Cubecubed 💖 d3.js

Duc Phat — Thu, 21 Jul 2022 14:33:45 +0000

d3.js is a JavaScript library used to manipulate the DOM through cake-simply syntax. You can think of it as the next-gen version of jQuery, but not quite. d3.js specifically focuses on data visualization. In addition, it helps you work with animations played by the tweening way (aka not WebAPI's requestAnimationFrame).

Cubecubed intensively uses d3 in all SVG-related cubicon classes. In this article, I will show you the basic things you need to know about d3, and in the end explain how Cubecubed uses it to abstract the SVG rendering process in classes.

So, let's start with the basic d3 methods.

`append()`, `select()`, `attr()` and `style()`

In index.html, we define these tags inside the <body> element:

<h1>Hello</h1>
<h1>World</h1>

There is another way to achieve this entirely in JavaScript. We don't need to edit the HTML file then.

d3.select("body")
  .append("h1")
  .text("Hello");

d3.select("body")
  .append("h1")
  .text("World");

When we call select("body") method, d3 will find the first body element and return a d3 selection object of it.

Next, we select the first <h1> like so:

d3.select('h1');

Then, if we apply an attribute to the element, we can simply chain the code above with attr() method.

d3.select('h1')
  .attr('class', 'hello');

The rendered HTML on the browser will be like so:

<h1 class="hello">Hello</h1>
<h1>World</h1>

How can we apply CSS styles to the element? You guess it.

d3.select('h1')
  .attr('class', 'hello')
  .style('color', 'red');

The magic of data join

Consider this HTML structure:

<h1>red</h1>
<h1>green</h1>
<h1>blue</h1>

How can we add the corresponding color to each of the h1 element? One way to do this is adding classes, select() the elements and apply colors to each of them. Something like this will work:

<h1 class="red">red</h1>
<h1 class="green">green</h1>
<h1 class="blue">blue</h1>

d3.select(".red")
  .style("color", "red");

d3.select(".green")
  .style("color", "green");

d3.select(".blue")
  .style("color", "blue");

What are the downsides of this approach? We have to add custom classes to the three h1 elements, and then violate the DRY principle by rewriting the classes when applying colors. Imagine the larger problem where we have hundreds of elements, I don't know about you, but to me I won't bother add hundreds of classes and then write hundreds of select() methods.

Maybe you have different approach from mine, but there is an awesome method built into d3 that perfectly works with this situation. That is the data() method.

First, let's define an array of color strings.

const colors = ["red", "green", "blue"];

After that, we bibidi-babidi-booo with these lines of code.

d3.selectAll("h1")
  .data(colors)
  .style((d, i) => d);

And boom, everything just works!

What is going on here? First, we select all h1 elements, then call the data() method on them. From this point, every next method in the current chain can take in an anonymous function with d and i as parameters. These two parameters are exactly like those are in JavaScript map() method: d is the current item, and i is its index in the array.

With just three lines of code, we don't need to add any classes or call any method a hundred times. The reasonable result is that the array (along with objects are the data in d3) needs to be updated to a hundred times then, which is no big deal if you have an active data store running.

This is the nature of the term "data visualization" of d3. With more and more data passed into the data() method, we can even create many SVG elements to easily visialize the data with graphs or charts.

`transition()` kickstart

The next thing that makes d3 a beast is its transition() method. I used this in all types of SVG animation in Cubecubed.

No more talking, let's dive into the code right now.

First, we append an SVG <circle> element into the body. The returned selection should be assigned to a variable.

const circleSelection = d3.select("body")
  .append("circle")
  .attr("cx", 50)
  .attr("cy", 50)
  .attr("r", 50)
  .attr("fill", "none")
  .attr("stroke", "#ffc777");

To translate the rendered circle, we call the transition() on the selection variable.

circleSelection
  .transition()
  .delay(1000)
  .duration(2000)
  .attr("transform", "translate(50, 50)");

In the code above, we set the delay time (the amount of time before the animation can be played - in milliseconds, so 1000ms = 1s), along with the duration of the animation. Specifically, the animation waits 1 second, then slowly tweens the SVG transform attributes until it reaches the value of translate(50, 50). The tween takes 2 seconds to finish itself.

The reason why we tween the translate attribute but not the cx and cy is that it appears in all SVG elements, while the two latter ones are defined specifically for <circle>. In Cubecubed, cubicon types have different base elements, from <circle> to <line> and so on. By that point, I want to utilize the Translate animation class for all of them.

Cubecubed's principle for creating new cubicon types

All cubicon types should be derived from Cubicon abstract class. There are two mandatory properties: g_cubiconWrapper and def_cubiconBase that you need to assign d3 selections to in the constructor. The former is an SVG <g> element that wraps around the latter, which is any SVG element that directly renders itself on the screen.

All append() method should be put inside the constructor. If you place it in the render() method, the HTML structure will be filled with the appended elements every time the users call the method, which results in a mess.

Conclusion

That's all you need to know about d3 library and how Cubecubed renders its cubicons.

How the animation engine of Cubecubed works?

Duc Phat — Thu, 30 Jun 2022 07:44:16 +0000

Hello, everyone. It has been a tough day to me so far. Nah, it's okay, I can continue working with Cubecubed.

Summer of Math Exposition 2 (#SoME2) ~~deadline~~ is coming to town. If you haven't heard about it but want to make an explanatory math video then I would encourage you to join in the competition. August 15 is the deadline (we are much far from there).

Cubecubed is the tool our team use for the final entry. It's not so great because it lacks a lot of features we need.

But my point is not just that.

As I said in the last article, my ambition for maintaining Cubecubed is to build a tool for teachers and students to visually interact with math. Cubecubed, still, has not gained much popularity, nor Manim nor any other visualization tools out there. So now, I am here, listing them to spread the word of teaching and learning math in a new way.

The first version - the bad, the worst and the horrible

Back when I first implemented the animation engine, it was a complete mess. The code is even the mystery to me, let alone other people. Maybe they just pass by the repo to see what is inside, or they want to contribute to it. I realized that is not fair to them. So I simplified it to a whole new level.

Now I want to share it with you.

The new one

Let this small video exemplify it.

The full code listing for the video is here. We will not talk about the whole thing, but focus more on the animation stuff.

Let's play the first animation.

group.play([new Create({ cubicon: square1, duration: 2000 })]);

Here, group.play() takes in an array of animations to play, which are technically called a queue in Cubecubed. The current queue has only one animation Create.

The man behind the mystery - `groupElapsed`

In Group class, groupElapsed is a trivial property. It is the heart of the animation engine. When the engine sees the above line of code, it will play all of the animations included in the queue then calculate the time needed (which we call queueElapsed) to finish them. queueElapsed now has the value of 2000 (2 seconds).

Move on to the next queue!

group.play([
    new Create({ cubicon: square2, duration: 2000 }),
    new Rotate({ cubicon: square1, duration: 3000, degree: 45 }),
]);

Line up, guys!

We all want the second queue plays after the last one has finished. Actually, this is a thing in Cubecubed. Queues are played sequentially, one after another. So what is the magic here? If you inspect the code of Cubecubed on GitHub, you'll see the play() method of all animation classes take sleepTime as a parameter. sleepTime is the amount of time to wait before playing.

But how can we calculate this sleepTime magic?

It's really simple. sleepTime is just Group().groupElapsed in disguise. Passing the former to the play() methods solves everything.

Queue-mon says: "Just play, don't wait"

We can see there are two animations in the queue now, Create and Rotate. Keep in mind, all animations in the same queue will play asynchronously. But what exactly happens behind the scene?

Similar to the last queue, the current one needs to calculate the queueElapsed. But how?

(Just to remind you, groupElapsed is now 2000)

Because the animations play asynchronously, we just need to take their maximum duration. Pseudocode: queueElapsed = max(2000, 3000) = 3000, then groupElapsed = groupElapsed + queueElapsed = 2000 + 3000 = 5000.

Any next queues will have to wait 5 seconds, and so on.

Guide for contributions

If you plan to code a new animation and create a PR to the GitHub repo, make sure the class has:

the constructor which takes in params parameters, an object with cubicon, duration and ease properties. If the cubicon property accepts two or more cubicon types, please define the union TypeScript type for it.
a play(sleepTime: number) method. Then, create a private method, name it as the (camelCase) form of the class name (CamelCase). Finally, call it from the play() method.

Phew, just imagine how many words I would have written in this article if the animation engine did not improve. It would be a... Anyway, that is everything of the animation engine. In the next article, I will talk about d3 and how to render cubicons with it. It will definitely the great resource for you if you want to contribute to the Cubecubed project. So, stay tuned.

My story with Cubecubed

Duc Phat — Mon, 06 Jun 2022 14:14:51 +0000

Hello fellow developers on the Dev Community, this is my first post here. Today I want to tell you my journey with Cubecubed - a visualization engine for playing math animations right on the browser. Though it's just a small project of mine, I'm very proud of it. This is not a promotion post for its GitHub repo, but a story I want to tell you.

Manim and Me

Just a little bit about myself: I'm a math enthusiast and a big fan of 3Blue1Brown's videos using the Manim engine.

When I first saw Grant's videos on YouTube, I was so inspired by the quality of them. After that, I learned that Grant used a Python library called Manim to produce those videos. The first time I used Manim, it took me about half a day to just install it on my Windows machine (though Linux is completely ok). I have to tell you, the engine is great, but the installation and MP4 converting process is a pain in the ass. Besides of that, I want Manim to be accessible for everyone, ranging from teachers and students to math lovers like me, especially the ones who don't know how to code, and don't spend time learning it.

So I had an idea: why don't I create a web version of Manim and turn it to a web app? That way, the users can click around, use the UI to achieve exactly the things that can be done by programming.

Let the journey problems begin!

I tried Django. Frankly said, I'm too lazy to learn a whole new framework in a language that I'm not comfortable to work with. But there is a much larger problem: the users spend time creating math animations but cannot view the result immediately. I mean, they use the application and convert their Manim project to an MP4 file; if anything goes wrong they have to go all over again to find the "bug" and have no idea where it is. Even when they fix the "bug", they have to painfully wait for the converting process (and unfortunately, they find more bugs).

I thought, "what can be the solution for both of those issues?" You can make a guess... That's right, the web! The browser is a wonderful place for playing dynamic animations and creating front-ends.

From that time being, I took time to search for promising JavaScript libraries, and spent a lot of time playing with Three.js and Anime.js and GSAP and much more. Some of which are simply bloated for my use case, and the others don't have enough features. Then I met my best friend: d3.js. It's tiny yet powerful, and above all, the 'transition()' method. Paradise!

Publicize my project

In December 2021, the first commit of Cubecubed was pushed to GitHub after a ton of customizations and refactoring. The first cubicons (equivalent to 'mobject' in Manim) were implemented, the name 'Cubecubed' and the project's logo was 'thought-provokingly' created.

Initially, I wrote it in JavaScript, and some people on Reddit suggested me to covert it to TypeScript. I did convert it, with the help of an awesome developer on GitHub (@marvin-j97). I want to give a big thanks to the contributors, along with the people who saw my posts on Reddit and gave me nice words and suggestions to improve Cubecubed.

Here are some showcase videos made by Cubecubed.

And that's it!

Cubecubed is the project that I put a lot of time and efforts into. The making of it is always an enjoyable journey to me. I want to say that, the most important things are not GitHub stars but the time you spend fixing bugs and learning new things.

Have a nice day everyone.