DEV Community: Ola B

Know Your WebDev Math: Translating coordinates with transformation matrix

Ola B — Wed, 10 Jun 2026 20:01:48 +0000

When I needed to pass Calculus and Algebra during my Computer Science degree, I used the formula known to every Polish student called 'ZZZ' (Zakuć, Zdać, Zapomnieć) - Cram, Pass, Forget. It means memorizing just enough to pass the exam and then not caring if you'll remember any of it later.

Fast forward a few years into my web developer career and I needed to implement a mouseMove event on the SVG element. Every move I made with my mouse made the element's position shoot off into the void. I solved this issue using the transformation matrix.

The more I worked with SVGs and graphs, the more I realized that the math I tried to cram and forget shows up in everything that I do. From the coordinates to graph layouts, drag-and-drop to animations - we just don't call it 'math'.

This series attempts to show you that math. Each article takes one concept (that we had to cram in class) and shows exactly where it lives in real frontend code, with real examples I've built in production or in side projects. I don't want to show you mathematical proofs, I will explain a bit of theory with a demonstration how to use it when you are the one who has to position elements just the right way, resolve conflicts and overlaps or draw a line from one point to another.

Welcome to Know Your WebDev Math.

Part 2: Translating coordinates with transformation matrix

Introduction

This is the problemI already hinted at in the intro to the Know Your WebDev Math series. No big requirements this time - just trying to build drag-and-drop of SVG elements inside a viewport.

If you try to pass coordinates directly from drag-and-drop mouse event to SVG, this will happen:

Points will be moved seemingly independently from the moves of the mouse cursor.

And how we want it to look like? I believe like this:

What is the difference between the first example and the second? A single line of code:

p = p.matrixTransform(m.inverse());

And in this article, I will explain, why.

Solution: Transformation matrices

Theory: what is a transformation matrix?

(Last time we talked about triangles. Today's starting topic: matrices)

A matrix is a mathematical object that structures numbers (or other objects) in rows and columns. Matrices (especially square matrices) have multiple usages in algebra, numerical analysis and geometry, thanks to their properties. One of matrices used in geometry is a transformation matrix.

A transformation matrix is a structure that describes how to move, scale, rotate, or skew points in space. In the context of 2D graphics (which is where we live as web developers working with SVGs), it's a 3×3 matrix (3 rows, 3 columns) where third row is always [0, 0, 1]. The remaining 6 values - [a, b, c, d, e, f] - describe all possible 2D transformations:

| a  c  e |
| b  d  f |
| 0  0  1 |

a and d handle scaling
b and c handle rotation and skewing
e and f handle translation (moving)

You don't need to memorize this. What matters is understanding that this matrix encodes the transformation necessary, to move the point from one system of coordinates to another. In our case: the coordinate system of the screen, and the coordinate system inside the SVG viewport.

If you want to go deeper, MDN's Matrix math for WebGL and the Aspose SVG transformation docs both have excellent explanations.

Another special type of matrix is identity matrix. This is a matrix that has 1 on the diagonal and 0 everywhere else.

| 1  0  0 |
| 0  1  0 |
| 0  0  1 |

If we use an identity matrix as a transformation matrix - nothing will happen. Nic. Zilch. Nada.

Working with points and matrices in JavaScript

The browser exposes two classes from the Geometry Interfaces Module that we'll need:

DOMPoint - represents a 2D (or 3D) point:

const p = new DOMPoint(x, y);

DOMMatrix - represents a 2D or 3D transformation matrix. You can create one manually, but in practice you'll get it from the browser (more on that in a moment):

const m = new DOMMatrix([a, b, c, d, e, f]);

The useful part is that DOMPoint has a method called matrixTransform - it applies a given matrix to the point and returns the transformed coordinates:

const transformedPoint = point.matrixTransform(matrix);

These two classes allow us to represent points and matrices - mathematical structures - in JS environment.

The SVG viewport and `viewBox`

Here's where the coordinate problem actually comes from.

An SVG element lives in the browser page and has a size in screen pixels, let's say 600×600px. But the SVG also has its own internal coordinate system, defined by the viewBox attribute:

<svg viewBox="0 0 1000 1000" width="600" height="600">

This tells the SVG: "my internal coordinate system goes from 0 to 1000 in both x and y, but render it into a 600×600 pixel box on screen." Every point you draw at (500, 500) in SVG coordinates will appear at (300, 300) screen pixels - because 500 out of 1000 = 50%, and 50% of 600 is 300.

Now here's the problem: when your mouse fires a mousemove event, it gives you screen coordinates - pixels relative to the top-left of the browser viewport. If you naively pass those into your SVG element's position, you try to apply external coordinates to internal system, and things can get 'jumpy'.

The fix is to convert from screen coordinates into SVG coordinates. And that's exactly what the transformation matrix is for.

`getScreenCTM()` - getting the matrix

We don't need to guess how the transformation matrix should look - SVG elements expose a method called getScreenCTM() (CTM stands for Current Transformation Matrix). It returns an object of the DOMMatrix class that describes the transformation from the SVG's coordinate system to the screen's coordinate system:

const m = svgElement.getScreenCTM();

Think of it like this: m knows how to go from SVG to screen. Apply m to an SVG point, and you get where it appears on screen.

But we want to go the other way, from screen to SVG. We have a mouse position in screen coordinates, and we need the equivalent SVG coordinates.

Inverting the matrix - reversing the translation

To go in the opposite direction, we need to invert the matrix. Inverting a transformation matrix produces a new matrix that undoes exactly what the original does.

Mathematically, if A is our matrix and A^-1 is inverted matrix A, multiplying them both will give us identity matrix.

And I remember that because I had to retake the test on inverting matrices during algebra course in uni.

So our m matrix will transform from SVG to screen, and we need to find mInversed that will transform from screen to SVG.

Fortunately for me and my algebra skills, DOMMatrix gives us this for free:

const mInverse = m.inverse();

And that brings us back to the one-liner from the intro:

p = p.matrixTransform(m.inverse());

We take the point p (in screen coordinates from the mouse event), apply the inverted CTM, and get back the correct position in SVG coordinates.

Calculations

Let's walk through exactly what happens in the final code. It's a Vue 3 app with an SVG element that has draggable endpoints.

Setting up the SVG and drag events

<svg
  viewBox="0 0 1000 1000"
  @pointerMove="onDrag($event)"
  @pointerUp="onDragStop()"
  ref="container"
>
  <circle
    r="4"
    :cx="start.x"
    :cy="start.y"
    fill="purple"
    @pointerDown="onDragStart('start')"
    ref="start"
  />
  <circle
    r="4"
    :cx="end.x"
    :cy="end.y"
    fill="purple"
    @pointerDown="onDragStart('end')"
    ref="end"
  />
</svg>

The pointerMove is on the SVG itself (not the circles) - this way we don't lose tracking if the mouse moves faster than the element. The ref attributes give us direct access to the DOM nodes, which we'll need to call getScreenCTM().

The drag handler

onDrag(e) {
  if (this.dragging !== null) {
    let p = new DOMPoint(e.clientX, e.clientY);

    if (this.dragging === 'start') {
      const m = this.$refs.start.getScreenCTM();
      p = p.matrixTransform(m.inverse());
      this.start = { x: p.x, y: p.y };
    } else if (this.dragging === 'end') {
      const m = this.$refs.end.getScreenCTM();
      p = p.matrixTransform(m.inverse());
      this.end = { x: p.x, y: p.y };
    }
  }
}

Step by step:

new DOMPoint(e.clientX, e.clientY) - wrap the mouse's screen coordinates in a DOMPoint.
this.$refs.start.getScreenCTM() - get the transformation matrix of the dragged element. This gives us the full picture of how the SVG is scaled, translated, and positioned relative to the screen.
m.inverse() - inverting the matrix - now the matrix translates screen → SVG.
p.matrixTransform(m.inverse()) - apply the inverted matrix to our screen-space point, getting the equivalent SVG-space coordinates.
Update the reactive data, and Vue re-renders the circle at the correct position.

Notice that we call getScreenCTM() on the circle element, not the SVG root. This is intentional - it accounts for any additional transforms applied to the element itself (rotation, scaling, nesting inside a <g> with a transform, etc.). The matrix you get is cumulative for the full chain from that element to the screen.

You can play with the full example here:

Result

With these ~3 lines of setup, you get perfectly tracked drag-and-drop in any SVG, regardless of:

how the SVG is scaled or positioned on the page
whether the viewBox matches the rendered pixel size
whether the SVG is inside a scrolled container

The matrix handles all of this for you.

One thing I want to highlight about Screen CTM: notice that the math itself is invisible. You're not computing scale factors manually, not applying CSS transforms, not doing trigonometry. You just ask the DOM for the matrix it's already maintaining internally, invert it, and apply it. The browser has been tracking this all along and getScreenCTM() just allows you to use the existing transformation. The geometry is already there. You just need to know that you can use it and what to use it for.

This is why we need math in programming - even if I failed my first matrix inversion test, I knew that I could use matrix to transform a point position and I could start to look for matrixes in JS.

Next up: Bézier curves — the math behind every smooth path in CSS, SVG, and canvas, and why those control point handles in your design tools are doing exactly what the formula says.

If you've run into SVG nightmares of your own (and I know you have), drop them in the comments!

Know Your WebDev Math: Dynamic positioning with trigonometry

Ola B — Fri, 29 May 2026 14:09:33 +0000

Welcome to Know Your WebDev Math.

Part 1: Dynamic positioning with trigonometry

Introduction

I play a ton of DnD. And in my longest and favourite campaign (Curse of Strahd) the relations within the party and between the party and important NPCs (Ireena) are extremely important. We keep an Excel spreadsheet describing the current relationship status (from 'love' to 'hate' to 'it's complicated'). And I had an idea of creating an interactive diagram of those relations.

Requirements

Every character avatar and name needs to be visible.
Every character needs to be connected to every other character.
The color of the connection symbolizes the relationship status.
Hovering over a character's avatar should show description of what they think of others and what others think of them.
The number of characters is not fixed.

Analysis

Graph is the best structure to show elements and their relations, so I decided to implement my diagram in React Flow.
To ensure good readability of the graph I decided to use circular graph layout:

It means that each character avatar should be positioned on the edge of the circle.
Only one question remained: How to dynamically position elements in the circle?

Solution: Trigonometry

Theory: sine and cosine

This is a right-angled triangle.

(Bear with me for a moment, I know you know what a triangle is. All of this will matter in a second)

It has 3 sides: opposite, adjacent and hypotenuse. It also has an acute angle, let's call this angle α.

We can calculate sine of α - sin(α) - by dividing the length of the opposite side by the length of hypotenuse side: sin(α) = opposite / hypotenuse.

Same with cosine of α - cos(α) - we need to divide the length of the adjacent side by the length of the hypotenuse side: cos(α) = adjacent / hypotenuse.

Sine and cosine are ratios, which means they stay exactly the same for every specific angle value. The sine of 30 degree angle is always 0.5 - it doesn't matter if the opposite side of a triangle has a length of 2 or 200.

How is it going to help us?

We want to position elements on the edge of the circle in equal distances from each other - we need to calculate x and y position of the centre of each element.

Let's go back to our circular graph. If we draw the line from the centre of the graph to the centre of one of the nodes, we can create a right-angled triangle in which the lengths of adjacent and opposite sides are our x and y, respectively.

We need to find the lengths of sides in our triangle. And we can do that using sine and cosine.

Calculations

The easiest side is hypotenuse - it's the radius of our layout circle, let's call this variable radius. It can be arbitrary, just adjust it to the size of your nodes.
The center of the graph (point C) can also be arbitrary, let's assume variable c of type Point: type Point = {x: number; y: number}.

To calculate the value of x - adjuscent side of triangle - let's change the cosine equation:
adjacent = cos(α) * hypotenuse.
And to calculate the value of y - opposite side - let's change the sine equation the same way:
opposite = sin(α) * hypotenuse.

We can calculate the sine and cosine values for specific angle α using functions from JavaScript Math library: Math.sin and Math.cos. Those functions take radian angle value as parameter.

So how can we calculate radian value of α?

We know that our graph is going to have n elements. And radian value of 360 degree angle is 2π.

So our α is: α = 2π / n or in JS: const alpha = (2 * Math.PI) / n.

Final calculation

Now, we need to iterate over each node and calculate its position (adjusting for center point c):

const updatedNodes = nodes.map((node, index) => {
        const angle = index * alpha;
        return {
          ...node,
          position: {
            x: c.x + radius * Math.cos(angle),
            y: c.y + radius * Math.sin(angle),
          },
        };
     });

Nodes above are graph nodes from React Flow, so if I'll set position property in the node object, React Flow will automatically place them for me.

Result

Behold, an example with Baldur's Gate 3 characters!

Additionally, you can adjust your radius variable based on the number of nodes in the graph to have fully dynamic graph, growing with the number of characters you want to have in your D&D (or DaggerHeart, or Call of Cthulhu or any other system) session.

I decided to start Know Your WebDev Math series with simple trigonometry, because sine and cosine are, for me, the symbols of 'that stupid math I won't ever use in my life' approach. Turns out, trigonometry was just waiting for me to build something worthy using it on.

If you play D&D or have a graph layout problem, drop it in the comments!

Next up: the tower of Babel of different coordinate systems, and how transformation matrix acts as a translator.

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

Ola B — Sat, 23 Nov 2024 17:32:44 +0000

I recently had to create a documentation page supporting OpenAPI spec documentation. What's an OpenAPI spec documentation? A page, either self-hosted or included in your API management platform, that allows users to check what endpoints, methods, webhooks, etc., are available based on OpenAPI JSON or YAML.

I needed to find a balance between needing as many customization options as possible and using ready-to-go tools for quick setup and deployment.

And I found Rapi Doc - a web component that can be embedded anywhere.

With the component ready, I needed a tool to write documentation that supported custom components.

So I chose Vitepress. And I had two tools that I wanted to merge. How did it go? Let's find out.

Running app in dev mode

I'll skip the story of Vitepress setup - you can find the instructions on their main page.

I also created a custom RapiDoc.vue component where I embedded my rapi-doc web component.

<script setup>
import 'rapidoc'
</script>

<template>
<div>
  <rapi-doc
      spec-url = "https://petstore.swagger.io/v2/swagger.json"
      render-style = "read"
      style = "height:100vh; width:100%"
  > </rapi-doc>
</div>
</template>

<style scoped>

</style>

I also embedded this custom component in a api-docs.md page (yes, you can embed Vue Components in Markdown, I love Vitepress for it!) so I could see it in my Vitepress documentation.

---
sidebar: false
layout: page
---

<script setup>
import RapiDoc from './components/RapiDoc.vue';
</script>

<RapiDoc />

I ran yarn docs:dev expecting everything to go smoothly (I followed the instructions from both documentations, so it should be fine, right?)...

And I got this:

And my browser froze.

Woohoo, long live the infinite loop!

What happened? So, since rapi-doc is a web component, I need to explicitly tell Vue compiler to not parse it. To just leave it alone.

And inside my config.mts file I needed to add:

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  ...
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag: string) => {
          return tag.indexOf('rapi-doc') >= 0;
        }
      }
    }
  },
})

We just need to check for custom elements and inform Vue "hey, this tag is off-limits".

So, we have it, it runs!

And then I tried to build it so I could set up deployment.

Building the app

I ran yarn docs:build command. And I immediately (wow, Vite, you're quick!) got this error:

This error means that during build-time, Vite couldn't access a self property. This can also happen if you try to access browser API (e.g., window) from server (in Nuxt or any other SSR framework, for example).

So what we can do? We can import it dynamically in runtime!

Let's change our import from this:

<script setup>
import 'rapidoc';
</script>

To this:

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  import('rapidoc');
});
</script>

And now build should pass with no issues! Enjoy you API spec docs!

Bonus: Dark Mode

Vitepress comes with dark mode, working out-of-the-box. But how can we make our RapiDoc documentation reacting to mode changes?

We can use Vitepress core composable - useData. It contains isDark property with information if the darkmode is enabled or not.

So let's use it inside the script section in the SFC:

<script setup>
import { useData } from 'vitepress';
import { ref } from 'vue';

const data = useData();
const theme = ref(data.isDark.value ? 'dark' : 'light')
</script>

Now when we have a theme ref, we can pass it to the rapi-doc Web Component via attribute binding:

<template>
<div>
  <rapi-doc
      spec-url = "https://petstore.swagger.io/v2/swagger.json"
      render-style = "read"
      :theme="theme"
      style = "height:100vh; width:100%"
  > </rapi-doc>
</div>
</template>

We need to add one more thing for dark mode to work correctly - responding to theme change.

Let's add a watcher to our script section:

watch(data.isDark, (isDark) => {
  theme.value = isDark ? 'dark' : 'light';
})

And voila, you created API docs that react to theme changes!

Animate your SVG text with animejs (and Vue)

Ola B — Thu, 18 May 2023 21:56:07 +0000

Are you looking for a non-standard portfolio page welcome text? Do you want to create an animated website to propose to your loved one?

Say no more!

In this #showdev I'll teach you how to create stunning SVG animation with an equally stunning animejs library!

The result will look like this:

NOTE: This post will show you how to create a line drawing animation in animejs. If you want it in a condensed form, straight from the source, visit the official documentation.

Prerequisites

To create a stunning animated SVG image, first, you will need SVG to animate. There are many tools to do that, available both online and offline. You can, for example, start with generating text using easysvg (written in php, but a great tool nonetheless).

Important: Every letter in your SVG should be a separate <path> tag! Here paths mark the outlines of the letters.

You will also need a container to run the animation in. It can be anything, pure JS script or a more advanced app. In my case, I'm using a very simple Vue.js app.

Preparing your SVG

To make our SVG look classy, we need to tweak it a bit:

To provide it with an "outlined" look, set fill attribute in every <path> tag to transparent and set stroke attribute to any color you want.
Add some extra elements for flavor - directly in SVG code (if you're the pro and a math nerd) or use some editor to do it.

Use my SVG, if you want: link to github file.

Animating

First, install animejs.

juliangarnier / anime

JavaScript animation engine

Anime.js

Anime.js is a fast, multipurpose and lightweight JavaScript animation library with a simple, yet powerful API.
It works with CSS properties, SVG, DOM attributes and JavaScript Objects

Usage

Anime.js V4 works by importing ES modules like so:

import {
  animate,
  stagger,
} from 'animejs';

animate('.square', {
  x: 320,
  rotate: { from: -180 },
  duration: 1250,
  delay: stagger(65, { from: 'center' }),
  ease: 'inOutQuint',
  loop: true,
  alternate: true
});

V4 Documentation

The full documentation is available here.

V3 Migration guide

You can find the v3 to v4 migration guide…

View on GitHub

Then add animejs animation:

anime({
    targets: document.getElementsByTagName('svg')[0].children,
    strokeDashoffset: [anime.setDashoffset, 0],
    easing: 'easeInOutBack',
    delay: function(el, i) { return i * 250 },
    direction: 'normal',
  });

Easy? Let me break it down line by line!

    targets: document.getElementsByTagName('svg')[0].children,

In this line, we point to every element we want to animate, in this case to an array of every child element of our SVG. You may need to adjust it a little to the structure of your SVG.

    strokeDashoffset: [anime.setDashoffset, 0],

This is what makes animation happen. It uses stroke-dashoffset attribute. If you want to know more about animating SVGs using this attribute, I recommend this CSS Tricks article.

    easing: 'easeInOutBack',

I wanted to add a little "bouncing" at the beginning and the end of the animation of every letter. If you want to test different easing functions on your own, I recommend easings.net.

    delay: function(el, i) { return i * 250 },

I wanted to slightly delay every animated path, so I passed a function that multiplies the delay by the index of an element in the table I passed in targets.

    direction: 'normal',

You can choose from normal, reverse, and alternate.

Embed this... somewhere

Although animejs can be used in Vanilla, I really wanted to use it in my Vue.js app.

I used Vue.js transitions to do that. More on them.

First, template:

<Transition appear :css="false" @enter="onEnter" name="howdy">
  <!-- Your SVG goes here. I used v-html because I'm lazy ¯\_(ツ)_/¯  -->
  <div v-html="howdy" />
</Transition>

You can use SVG Component to embed your SVG on a page.

I wanted my animation to start on a component render, so I added appear keyword to the transitions. I also needed to tell Vue this animation would be purely JS, so I used :css="false".

Now I only need to write onEnter callback:

const onEnter = (el: Element, done: () => void) => {
  anime({
    targets: el.getElementsByTagName('svg')[0].children,
    strokeDashoffset: [anime.setDashoffset, 0],
    easing: 'easeInOutBack',
    delay: function(el, i) { return i * 250 },
    direction: 'normal',
    complete: () => {
      done();
    },
  });
}

onEnter uses the Transition Element as the first argument and done() function as the second. We have to call done() function at the end of the application to signal to Vue that the animation ended. We can use complete hook from animejs to do it.
And we want to animate only descendants of our Transition element, so we can specify targets using the first argument.

And... that's it! Sit back and enjoy your animated text!

If you have any questions, I'm happy to answer :) If there's anything to be improved in this short post, let me know, and I'll gladly fix that!

And if you want to see this animation in action, you can visit my page (I have to warn you though, this is still in a WIP stage).

All the best,

Aleksandra (or Ola, for short)

DEV Community: Ola B

Know Your WebDev Math: Translating coordinates with transformation matrix

Part 2: Translating coordinates with transformation matrix

Introduction

Solution: Transformation matrices

Theory: what is a transformation matrix?

Working with points and matrices in JavaScript

The SVG viewport and viewBox

getScreenCTM() - getting the matrix

Inverting the matrix - reversing the translation

Calculations

Setting up the SVG and drag events

The drag handler

Result

Know Your WebDev Math: Dynamic positioning with trigonometry

Part 1: Dynamic positioning with trigonometry

Introduction

Requirements

Analysis

Solution: Trigonometry

Theory: sine and cosine

How is it going to help us?

Calculations

So how can we calculate radian value of α?

Final calculation

Result

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

Running app in dev mode

Building the app

Bonus: Dark Mode

Animate your SVG text with animejs (and Vue)

Prerequisites

Preparing your SVG

Animating

juliangarnier / anime

JavaScript animation engine

Anime.js

Sponsors

Platinum sponsors

Silver sponsors

Usage

V4 Documentation

V3 Migration guide

Embed this... somewhere

The SVG viewport and `viewBox`

`getScreenCTM()` - getting the matrix