CPU Bitmap Affine Transformations

Test Coverage:

View detailed coverage report

Introduction

The purpose of this repository is to be an educational resource on the math behind the CSS transform property. It's self-contained, therefore, no third party libraries or build system is used. Even though CSS transform is hardware accelerated via the GPU I decided to stay away from WebGL to keep the focus on the math.

Getting it up and running

This project is built using native ES modules, therefore, you'll need to serve up the files in this project with a web server (See the troubleshooting section of the MDN ES module guide for a more detailed explanation). Running ./scripts/run.sh (will not work on Windows) from the root directory of this repository will start up a web server serving up the right files at http://localhost:8000, if your system has Python2 or Python3 installed. You can also use another web server of your choice.

Prerequisite Knowledge

I strongly recommend a understanding of the following basic linear algebra topics:

• Vectors
• Dot product
• Linearity
• Matrices
• Matrix multiplication
• Elementary row operations
• Gauss Jordan Elimination
• Computing the determinant of a matrix
• Computing the inverse of a matrix

If you're unfamiliar with these topics, the following are good resources:

• The Essence of Linear Algebra video series on YouTube from 3Blue1Brown provides an interesting and approachable introduction to the core concepts of linear algebra. It does a good job of building a conceptual understanding, but it's light on mechanics.

• If you want to explore linear algebra more in depth, the legendary Gilbert Strang's Introduction to Linear Algebra is a great book and was the book that was used in the linear algebra course I took in college.

General Overview of Code Base

• Matrix A class that has methods for basic operations that can be performed on matrices and vectors (Matrices that have one dimension of size 1 can use the vector operations)

• scale(x, y) A function that generates a scale matrix

• rotate(degrees) A function that generates a rotation matrix

• translate(x, y) A function that generates a translation matrix

• parseTransformCommands(commands) Parses a string containing transform commands into an array of command objects

• computeTransformMatrix(commands) Takes a string containing transform commands and returns a matrix encoding the associated affine transformations

• transform(imageData, commands) Takes ImageData and transform commands and returns a copy of the ImageData with the commands applied

• getBitmap(selector) Takes a CSS selector and returns the image data of the selected image

• imageDataToImage(imageData) Produces a data url from the provided image data

• getPixel(imageData, x, y) Returns an Uint8ClampedArray of the RGBA values of the selected pixel

• setPixel(imageData, x, y, color) Writes a RGBA color to the image data at the specified pixel

Unit tests

If you would like to contribute to this project, there is a suite of tests written with Jest located in the tests directory.

Setup

• Jest requires Node.js and npm to be installed. See this guide for instructions, if you don't have it installed.

• After this you'll need to have Jest installed globally which can be done by running npm i -g jest.

Running the tests

• These tests can be ran by running ./scripts/tests.sh (will not work on Windows) from the root directory.
• This project is also configured to work with VSCode's Jest extension and the test suite can be ran and debugged via it.

CI and contributing

This repository has a Github action that will run the test suite, after every push. The file that defines it is located here ./github/workflows/node.js.yml. Pushing directly to master is not permitted. Github will only permit merging into master, after the action passes.