JavaScript on David Hamann

SVG and JavaScript: transform viewport coordinates into element coordinates

Fri, 13 Jan 2023 00:00:00 +0000

A couple of months ago I built a JavaScript application that allows adding points and labels to locations on a building floorplan. The whole canvas (not HTML <canvas>) is a SVG document inside an HTML document and points/objects/labels/etc. are added to that canvas as native SVG elements.

Users can add/move objects on the floorplan but also zoom and pan the floorplan itself.

When performing these actions it is important to transform coordinates from the screen or viewport (like the position of your mouse/fingers) into coordinates that make sense in your SVG element’s coordinate system.

In this post I want to share some of my notes and a simplified example on how to achieve this using a group element with a transform attribute and a few objects (circle elements) inside.

Panning, Zooming, Dragging

Let’s say we have a setup as shown in the following Gif:

We can move the canvas, we can move objects, zoom in and then move objects again in a zoomed/panned state.

If you look at the inspector window you see that the zooming and panning is performed by changing the transform attribute on the group element with id main, and that moving an object (a circle element) just changes the respective cx and cy values (as the objects are inside the transformed group).

All the movements follow the mouse pointer in a reasonably fast manner.

Implementing the start of the pan

A first (incomplete) approach to implementing the panning or dragging could be to store clientX and clientY from the mousedown or touchstart event and then calculate the difference to the clientX and clientY from the mousemove or touchmove event. While this difference represents the amount the mouse moved in the browser’s viewport (window), it cannot be directly applied to the transformation matrix of our main element as the SVG document on the page may not cover the whole viewport, might be in a scaled state, etc. – in any case, we have at least two different coordinate systems.

The effect when not translating the coordinates is usually that objects move either much faster or much slower than your mouse pointer.

Let’s now see how we can transform the coordinates you get from events to coordinates you can use in your SVG document.

A minimal HTML document with an SVG document inside (as seen in the Gif above) could look like this:

<html>
 <head>
 <title>SVG app</title>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1">
 </head>
 <body>
 <div id="canvas-wrapper">
 <svg
 id="canvas"
 viewBox="0 0 1024 768"
 preserveAspectRatio="xMidYMid"
 xmlns="http://www.w3.org/2000/svg"
 >
 <g
 id="main"
 transform="matrix(1 0 0 1 0 0)"
 >
 <image
 x="0"
 y="0"
 width="1024"
 height="768"
 xlink:href="background.png"
 ></image>
 <!-- some "random" points -->
 <circle id="p1" cx="512" cy="284" r="4" fill="blue" stroke="black" />
 <circle id="p2" cx="500" cy="300" r="4" fill="red" stroke="black"/>
 <circle id="p3" cx="490" cy="330" r="4" fill="red" stroke="black" />
 <circle id="p4" cx="430" cy="250" r="4" fill="red" stroke="black" />
 </g>
 </svg>
 </div>
 </body>
</html>

Let’s say we want to start our panning action when the user clicks on the div with the id canvas-wrapper.

Once the document is ready, we register the event listener, for example like this:

document.getElementById('canvas-wrapper').addEventListener('mousedown', onPanStart);

Our function onPanStart could look like this:

function onPanStart(e) {
 const {clientX, clientY} = e;

 // get our own transform matrix from the main element
 // (we will modify this as we move our mouse along)
 const currentTransform = getTransform();

 // get the transform matrix used to convert from the SVG element's
 // coordinates to the screen/viewport coordinates
 const sctm = document.getElementById('main').getScreenCTM();

 const mouseStart = transformFromViewportToElement(clientX, clientY, sctm, currentTransform);

 canvas = {
 mouseStart,
 transform: currentTransform,
 sctm
 }

 document.getElementById('canvas-wrapper').addEventListener('mousemove', onPan);
 document.getElementById('canvas-wrapper').addEventListener('mouseup', onPanEnd);
}

In a nutshell:

We get the clientX and clientY representing the point in the viewport where the event (mousedown) occured.
Then we get the transform matrix of our main group (in the beginning [ 1, 0, 0, 1, 0, 0 ]) which we later use to translate/scale. The getTransform function simply reads the transform attribute and creates an array from it:

function getTransform() {
 const matrix = document.getElementById('main').getAttribute('transform');
 return matrix.replace(/^matrix\(/, '').replace(/\)$/, '').split(' ').map(parseFloat);
}

Also from our main SVG element, we get the matrix that transforms the element’s coordinate system to the viewport’s coordinate system.
Now comes the interesting part: we transform our coordinates from the event into coordinates for the element’s coordinate system (transformFromViewportToElement function explained below).
Finally, we store the values in variable named canvas (let canvas = {}) for later access and add the event listeners for the actual panning (mousemove) and end (mouseup).

All the magic happens in the transformFromViewportToElement function:

function transformFromViewportToElement(x, y, sctm=null, elementTransform=null) {
 // Transforms coordinates from the client (viewport) coordinate
 // system to coordinates in the SVG element's coordinate system.
 // Call this, for example, with clientX and clientY from mouse event.

 // create a new DOM point based on coordinates from client viewport
 const p = new DOMPoint(x, y);

 // get the transform matrix used to convert from the SVG element's
 // coordinates to the screen/viewport coordinate system
 let screenTransform;
 if (sctm === null) {
 screenTransform = document.getElementById('main').getScreenCTM();
 } else {
 screenTransform = sctm;
 }

 // now invert it, so we can transform from screen/viewport to element
 const inverseScreenTransform = screenTransform.inverse()

 // transform the point using the inverted matrix
 const transformedPoint = p.matrixTransform(inverseScreenTransform)

 // adjust the point for the currently applied scale on the element
 if (elementTransform !== null) {
 transformedPoint.x *= elementTransform[0]; // scale x
 transformedPoint.y *= elementTransform[3]; // scale y
 }

 return {x: transformedPoint.x, y: transformedPoint.y}
}

I commented each step in the function above. Essentially, we create a point with our event coordinates, take the matrix used to convert from the element to the viewport, invert it (since we want the opposite) and then do a matrix transform of our point with said matrix. In case we are working with a transformed element (as is the case for our canvas panning, but not for object dragging) and are in a zoomed-in/out state, we also want to apply that scale to our coordinate.

Actual panning and ending

To complete our basic example, let’s see how the onPan and onPanEnd functions could look like:

function onPan(e) {
 const {clientX, clientY} = e;
 const client = transformFromViewportToElement(clientX, clientY, canvas.sctm, canvas.transform);

 // calculate how much we have moved from the starting point
 const movement = {
 x: canvas.mouseStart.x - client.x,
 y: canvas.mouseStart.y - client.y
 };

 // set `tx` and `ty` (translate x, y) of matrix with the offset that
 // was set at the beginning of the movement minus the actual movement.
 const startMatrix = [...canvas.transform];
 startMatrix[4] = startMatrix[4] - movement.x;
 startMatrix[5] = startMatrix[5] - movement.y;

 // update the actual transform attribute of the SVG `main` group
 document.getElementById('main').setAttribute(
 'transform', `matrix(${startMatrix.join(', ')})`);
}

function onPanEnd(e) {
 canvas = {};

 document.getElementById('canvas-wrapper').removeEventListener('mousemove', onPan);
 document.getElementById('canvas-wrapper').removeEventListener('mouseup', onPanEnd);
}

In the onPan function we get and transform the new event coordinates (where the mouse pointer is now) in the same way as we did before, then calculate the difference between start and current position, apply the difference to the original (at start of pan) transform matrix’s tx and ty (index 4 and 5), and finally set the transform attribute of main to the updated matrix.

Note that we are changing the matrix of our transform attribute of the group here – this is not the matrix obtained by getScreenCTM!

In onPanEnd we simply reset our global canvas variable and then remove the listeners.

Dragging and dropping objects

The dragging of objects could be implemented in the same way (using transformFromViewportToElement). The only difference here is that we would modify the x and y coordinates (or rather cx and cy) directly (instead of a transform attribute), and also ignore the current scale of the group element’s transform matrix (set elementTransform parameter of transformFromViewportToElement to null).

Remote debugging Claris Data API

Wed, 04 May 2022 00:00:00 +0000

When debugging code that integrates with the Claris FileMaker Data API, it is sometimes helpful to trace a request from your app all the way to the code of the Data API. You might be getting an unexpected error response, want to see what data actually arrives on the server, how a wrapper library, if you use any, might translate the request/response, etc.

Doing this kind of troubleshooting is much easier when you are able to directly attach a debugger to the remote process. This blog post describes a few steps you can take to remotely debug Data API requests.

Start here! As the Data API is a NodeJS application, we need a typical remote debugging setup for JavaScript. Please read my last post on Remote Debugging NodeJS apps first, if you haven’t already done so. We will use the exact same tools in this post.

Preparing the start script

I’m using a FileMaker Server on macOS for this article. If you want to follow along on a different OS, make sure to use the pathes that correspond to your platform.

The first thing we want to do on the FileMaker Server is to stop the Data API with fmsadmin stop fmdapi.

Next, we need to do a slight modification in a shell script responsible for starting the Data API. Remember from the above linked blog post that we want to start the Inspector service along with the target NodeJS app. The place where this happens is in /Library/FileMaker Server/Web Publishing/publishing-engine/node-wip/wipdeploy.sh:

# [...]

 INSTALL_ROOT="/Library/FileMaker Server"
 WIPNODE_PATH="$INSTALL_ROOT/node"
 NODE_PATH="${WIPNODE_PATH}/bin/node"

# [...]

WIP_NODE_DIR="$INSTALL_ROOT/Web Publishing/publishing-engine/node-wip"
WIP_NODEJS="$WIP_NODE_DIR/app.js"

# [...]

if [ "$1" = "start" ] ; then
 echo "Starting WIP node"
 shift

 if [ "$1" = "-p" ]; then
 shift
 WIPNODE_BASE=$1
 fi

 echo "Execute node JS $NODE_PATH $WIP_NODEJS"
 "$NODE_PATH" "$WIP_NODEJS" "-$WIP_COMP"

As you see in the script, a couple of variables are set to define the install location and app file. Eventually, these variables make up the command to launch the Data API.

To tell NodeJS that we want to have a debugging endpoint listening we can add our extra argument --inspect (make sure to set the IP for your environment):

"$NODE_PATH" --inspect=172.16.157.133:9229 "$WIP_NODEJS" "-$WIP_COMP"

With this change in place (save your changes!) we can launch the Data API again, just like we normally would: fmsadmin start fmdapi.

Preparing our local environment

As described in the first blog post we need to have a copy of the source code of the remote app on our local machine as well. We can get this copy of the Data API NodeJS app from /Library/FileMaker Server/Web Publishing/publishing-engine/node-wip.

Opening the code with VSCodium on our local machine, the only thing left to do is to create a .vscode/launch.json configuration file and set the IP address of the FileMaker Server/Data API host and the assigned UUID:

{
 "version": "0.2.0",
 "configurations": [
 {
 "request": "attach",
 "name": "FMS Data API Debugging",
 "skipFiles": [
 "<node_internals>/**"
 ],
 "address": "172.16.157.133:9229/18de71ea-bc0a-4a15-8886-e3c1d24b8e72",
 "localRoot": "${workspaceFolder}",
 "remoteRoot": "/Library/FileMaker Server/Web Publishing/publishing-engine/node-wip/",
 "type": "pwa-node"
 }
 ]
}

The above config is the same as described in the first blog post. I obtained the UUID via curl http://172.16.157.133:9229/json/list.

Start debugging

Now that we have all things in place we can start the debugger in VSCodium and it should connect and attach to the Data API app on the remote host:

Two caveats

There are two additional things worth noting in this setup:

Please be aware of the warning in the first article regarding remote code execution, i.e. make sure to have a trusted environment and secure connection to your debugging endpoint.
While this setup gets you quite far in helping to understand what data arrives at the Data API application, what the expected format of the requests are, error messages being generated, behaviours not being described in the documentation, etc., it is much harder to analyse what happens as soon as the Data API makes a request to the database server via Thrift (as the database server source is obviously not open). Nevertheless, often times tracing the request until it is directed to Thrift will already aid you in identifying potential issues.

Remote debugging NodeJS apps

Tue, 19 Apr 2022 00:00:00 +0000

When you want to debug an application in an environment which is hard to replicate locally and/or you cannot install additional software on the machine it is running on, remotely connecting a debugger might be a good option to find out what’s going (wr)on(g).

Let’s have a look how we can remote debug a NodeJS application. I will use VSCodium as the debugging client, but there are certainly other options that work equally fine (you could even use the built-in minimal debugger with node inspect host:port).

Setting up the remote app

Let’s say we have the following minimal web application on our remote machine.

app.js:

const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
 res.send('Hello World!')
})

app.listen(port, () => {
 console.log(`Example app listening on port ${port}`)
})

In normal scenarios we can run the application with node app.js and it’ll start accepting requests on port 3000.

But NodeJS makes it easy to also launch a debugging endpoint, so-called Inspector, along with application:

node --inspect=1.2.3.4:9229 app.js

The above command will bind the Inspector service to the IP 1.2.3.4 and port 9229. Replace 1.2.3.4 with whatever interface you later want to connect to.

Note that opening up any debugger to the open world is generally a bad idea as access to the debugger essentially means you can execute any code in that environment. If you are not in a closed test environment where you trust the network and its participants, consider running the Inspector on the loopback address and then use SSH port forwarding for a secure connection.

Once the Inspector is running we need one more detail to connect to it: the UUID which is assigned when the process starts and which needs to be known to the connecting client.

If you don’t see it in the output when starting your app, you can connect to the following endpoint (on the interface you specified with --inspect) to discover it:

$ curl http://127.0.0.1:9229/json/list

[ {
 ...
 "id": "618339fa-2a18-4fea-b1f5-c20522e17a2b",
 "title": "app.js",
 "type": "node",
 "webSocketDebuggerUrl": "ws://127.0.0.1:9229/618339fa-2a18-4fea-b1f5-c20522e17a2b"
} ]

Setting up the local debugger

Back at our local machine we have three requirements:

We need a debugging client (I’m using VSCodium)
We need a copy of the source code of the application to debug
We need the address and UUID of the Inspector running on the remote machine

Let’s start by opening the folder with the source code (in this example with only the app.js file in it) in VSCodium.

Next, we create a “launch configuration” so that our debugger knows where and how to connect.

By default, the configuration will sit in .vscode/launch.json. For our sample app we use the following contents:

{
 "version": "0.2.0",
 "configurations": [
 {
 "type": "pwa-node",
 "request": "attach",
 "name": "Sample app",
 "skipFiles": [
 "<node_internals>/**"
 ],
 "address": "1.2.3.4:9229/618339fa-2a18-4fea-b1f5-c20522e17a2b",
 "localRoot": "${workspaceFolder}",
 "remoteRoot": "/path/on/remote/machine/",
 }
 ]
}

Essentially, we are saying that we want to attach to an existing process, define the address of the remote machine (including UUID), and point to the directories where the code resides locally and remotely.

Make sure to adjust the values for the keys address and remoteRoot to fit your setup.

Start debugging

With the launch configuration in place we can connect to the remote process by clicking on the “Run and Debug” button or just press F5.

With the client connected to the remote process, we can start setting breakpoints in the code, send a request (e.g. curl http://1.2.3.4:3000/) and then (as usual) use the debugger to inspect variables, step through the code, etc.: