Forem: Omar

Handmade GitHub Pages

Omar — Wed, 07 Jan 2026 14:50:03 +0000

This is part 2 of the "handmade computational sandbox" class. In part 1 (https://dev.to/omar4ur/handmade-cellular-automata-1f3c) we learned how to run a piece of JS code in a single HTML file on your computer, and how to deploy it on CodePen to share.

Today we're going to use GitHub for free static hosting, instead of CodePen. CodePen is good for quick experiments, GitHub is good for long term hosting.

For example, if you run a local community and want to set up a web page for it, a simple HTML page + a GitHub repo is perfect because (1) it's 100% free (2) if one day you leave town, the source code is available so someone else can copy it and continue to host it. This is designed to be very "permacomputing" and in line with Derek Siver's tech independence.

Example of a local community website made this way (just a single HTML file): https://mplawley.github.io/tundra-tech-talks/

If you're sharing a research prototype, this is also the perfect way to do it (live demo + source code available + a space for people to ask questions on the GitHub repo)

We're going to take the HTML/JS cellular automata simulation we created in part 1 and host it on GitHub pages. If you don't have your file from part 1, you can use this one that implements the game of life rules:

https://gist.githubusercontent.com/OmarShehata/9215085ff48882d1756ddd5ce2e0b912/raw/6ec921b6abd3dfc9f52a9be45989334cb1bb3c15/game_of_life.html

1. Create a new GitHub repo

Login or create an account on https://github.com/
Click "+" button in the top right -> "New repository"
Give it a name, toggle the "Add README" button. Click "create repository"

2. Add your HTML file

Click the "+" button in the top right of the repo and "create new file"

Call it index.html, and paste in your HTML/JS code

"index.html" is a special name, web servers will default to serving this as the homepage if they find it in a directory.

Click "commit changes"

3. Tell GitHub to deploy this website

Go to "settings" in the top right

Then "pages" in the left side panel

Here you will find the default settings for GitHub Pages, "deploy from branch". Just select your main branch here:

For bigger projects, you will have the code be in one branch, and the "built" thing to deploy in a different branch. For now, the code we are writing is itself the final code that runs in the browser, so we don't need this build step ("GitHub Actions" can be configured to run these build steps for you)

Hit "save"

4. Check the deployment status

If it worked, you should see this yellow circle back in the main repo page:

You can click on it to check the status. Once it's done, you can get the URL for your deployed website back in the Settings > Pages

Handmade Cellular Automata

Omar — Tue, 06 Jan 2026 18:59:09 +0000

This tutorial will walk you through creating & deploying your first "computational sandbox", an environment where you can define the rules of a simulation and explore the result. This is designed to be walked through together with a mentor.

This is the opposite of vibe coding - in order for you to use these simulations to think & learn about the world, you need to know everything about how it works. This is why we're doing everything "by hand". We're going to do the absolute minimum setup you need to (1) run things on a computer by yourself (2) share it with collaborators in a way that they can edit and build on.

Inspirations

Permacomputing
Derek Sivers' "tech independence" philosophy
- See also Rosano's Zero Data Apps & the Kosmos network
Casey Muratori's "Handmade Hero" series
Explorable Explanations
- Like the Parable of Polygons, a simulation about how sociology
- Cameras & Lenses, simulation about how cameras, light, and vision work
Internet art experiments like those done by Nolan (https://eieio.games/) & Neal (https://neal.fun/). See Nolan's newsletter
- Example of a simple research prototype that is only a few lines of code & a single HTML file, good & evil words

Overview of the series

(this article) How to run a piece of code in a plain HTML file on your computer, and deploy it on the internet with CodePen
Deploying a free static website or app on GitHub pages, like Ithaca Social Circle, or an Obsidian based website "digital garden"
- https://dev.to/omar4ur/handmade-github-pages-20pi
- mdBook template https://github.com/OmarShehata/mdbook-template/tree/main?tab=readme-ov-file#mdbook-template
Very basic backends ((1) using Google Sheets as a free backend, (2) or "BYO server" with remoteStorage, or (3) free CloudFlare object storage)
Basic user management with OAuth (twitter/google login)
Basic computer graphics visualizations (how to render pixels "raw", how to use a library like PixiJS or ThreeJS)
Basic data analysis (Jupyter notebooks & Google Colab)
- Simple twitter data NLP analysis
- ML cellular automata
Tips for navigating open source codebases, how to fork, edit, and contribute a pull request

In this lesson, you're going to setup this cellular automata simulation as a single HTML file on your computer, and copy/paste it onto CodePen to share it on the internet.

1. Install VS Studio Code

https://code.visualstudio.com/

We will use this as our IDE to edit code. The web browser is what will "run" the code.

You can use VS Code to edit any coding language, by either running the code outside of it, or finding a plugin that runs it for you.

2. Create an HTML file

This is just a text file with the extension .html. Inside of the HTML code we will embed the JavaScript code we want to run.

Create the file vanilla.html with VS Code, anywhere on your computer
Paste in the following code

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Vanilla JS</title>
</head>
<body>
    <p>Hello!</p>
    <script>
        // This is how you embed JavaScript inside of HTML
        console.log("Hello world!")
    </script>
</body>
</html>

Note: This series will not cover the basics of JS syntax. It's assumed you have a supplementary source or already know it. I recommend the book Eloquent Javascript, and the Codecademy JavaScript interactive lessons

Run this code by opening this file in your browser
Check the browser console to see if the JS code snippet ran correctly

Challenge: Can you make the web page display the current time?

You want to (1) get the current time in the JS code (2) Use document.querySelector() to select the HTML element and edit it with the local time (3) use setInterval to auto-update the code

Solution

Note: You can use the browser console as a REPL! You can expose a variable from your code by saying window.myVar = myVar, and then you have access to editing it live in your app

3. Deploy your code on the internet

This is the fastest way to get your code to run on millions of devices. It's "infinitely" scalable because the code runs on the user's computer, not on a central server. It's very cheap for CodePen, or any static host, because it's just delivering the code (consuming bandwidth, not CPU).

Make an account on https://codepen.io/
Create a new "pen"
Copy/paste your code into the "HTML" section of the CodePen interface
Click "Save" in the top right
To share it, click on the little icon of an arrow going out of a box, in the bottom right (on the same row as "Share" / "Export" / "Embed")

The shared link should look like this: https://codepen.io/omarshe7ta/full/wBWBqZq

You can continue writing code in the CodePen interface, or locally in VS Code.

4. Animated rectangle

Now we're going to run a piece of code that draws a rectangle that moves back and forth. Technically, the rectangle doesn't "move", we just erase the screen and redraw the rectangle at a new location at every frame.

Replace the code you have with this new template:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Vanilla JS</title>
    <style>
        html, body {
            margin: 0px; overflow: hidden;
        }
    </style>
</head>
<body>
    <!-- the "canvas" element is the box on the page, inside of which all the drawing will happen -->
    <canvas></canvas>
    <script>
        // set the height & width to be full screen
        const canvas = document.querySelector("canvas");
        canvas.width = window.innerWidth;
        canvas.height = window.innerHeight;

        const ctx = canvas.getContext("2d");
        let positionX = 25
        function loop() {
            // Clear the screen
            ctx.clearRect(0, 0, canvas.width, canvas.height)
            // Draw a rectangle, x, y, width, height
            ctx.fillRect(positionX, 25, 20, 20);

            // move the position for the next frame
            positionX += 1

            // run the function "loop" again
            requestAnimationFrame(loop)
        }

        // run the function "loop" once
        loop()

    </script>
</body>
</html>

Challenge: Can you move the box faster?

Challenge: Can you make the box start at the right edge of the screen and move to the left

Challenge: Can you make the box move back & forth?

To do this, set the X of the box to be the sine of your count variable. Sine of any number will give you a range of [-1, 1], and you can scale that to the range you want it to go back and forth in.

Solution

5. Cellular Automata Grid

Here we're going to start with a piece of code that sets up a grid of pixels with a random color. We'll use this as a base to explore various "cellular automata" simulations, like the Game of Life.

Replace the code you have with this:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Vanilla JS</title>
    <style>
        html, body {
            margin: 0px; overflow: hidden;
        }

    </style>
</head>
<body>
    <canvas></canvas>
    <script>
        const canvas = document.querySelector("canvas");
        canvas.width = window.innerWidth;
        canvas.height = window.innerHeight;
        const ctx = canvas.getContext("2d");

        const grid = {}
        const gridSize = 5
        initGrid()

        function loop() {
            requestAnimationFrame(loop)

            updateGrid()
            drawGrid()
        }
        loop()

        function initGrid() {
            // Fill the grid data structure with initial random colors
            for (let x = 0; x < canvas.width; x+= gridSize) {
                for (let y = 0; y < canvas.height; y+= gridSize) {
                    const color = Math.random() * 360
                    grid[`${x}_${y}`] = color
                }
            }
        }

        function updateGrid() {
            for (let x = 0; x < canvas.width; x+= gridSize) {
                for (let y = 0; y < canvas.height; y+= gridSize) {
                    let currentColor = grid[`${x}_${y}`]
                    // modify the color of the current square
                    // given the color it currently has
                    grid[`${x}_${y}`] = currentColor
                }
            }
        }

        function drawGrid() {
            // draw whatever is currently stored in the grid variable
            for (let x = 0; x < canvas.width; x+= gridSize) {
                for (let y = 0; y < canvas.height; y+= gridSize) {
                    const color = grid[`${x}_${y}`]
                    ctx.fillStyle = `hsl(${color}, 70%, 60%)`;
                    ctx.fillRect(x, y, gridSize, gridSize);
                }
            }
        }
    </script>
</body>
</html>

Try changing the gridSize variable at the top.

Challenge: Expose the grid variable to the browser console, so you can edit it in "real-time". Ask your LLM for a one-liner to take this data structure and set it all to 0, or some other constant

Challenge: Edit the updateGrid function to make the color change every frame

Challenge: Edit the updateGrid function to set the color of the current pixel, equal to the pixel to its left.

You'll need to handle the boundary condition to avoid errors.

Next lessons:

Deploy with GitHub Pages

Open source semantic embedding, search & clustering in NodeJS

Omar — Wed, 25 Sep 2024 15:43:24 +0000

This tutorial walks you through how to do semantic embedding completely offline with open source models in NodeJS. No knowledge of AI/ML is required. Source code: https://github.com/OmarShehata/minimal-embedding-template

An "embedding" is a high dimensional vector (x,y,z,...) that represents a concept. Think of it as the internal representation of words in an LLM. You can compute distances between these vectors.

Example: "Man" is much closer to "boy" & "woman", compared to "chicken". "Coffee" and "wifi" are somewhat close, and are both close to "coffee shop".

illustration of what these vectors might look like projected down to 2D

I think this is an extremely underutilized feature of modern LLM's, and it's much cheaper compute wise compared to text generation. Most of the time I don't really want the LLM to generate text as much as I want to see & manipulate the semantic concepts like this.

Setup

Clone the repo: https://github.com/OmarShehata/semantic-embedding-template. This contains a minimal NodeJS template that you can copy/paste and build on.

It uses (1) gpt4all as the LLM engine. This is where the open source model comes from, and is what converts a word/string/document into a vector. (2) Vectra as a local, single file vector database. Allows us to index & search vectors.

Run pnpm install, then run the first example in example-simple-embedding/index.js:

pnpm simple-embedding

This takes an array of strings and converts them to vectors:

await embeddings.insertText(['coffee shop', 'wifi', ...])

You can print the vectors with embeddings.getTextMap(). You can do a search as shown below. This returns a sorted list of the closest vectors in the DB, along with the cosine distance.

const results = await embeddings.search('coffee')
// returns:
// [
//   [ 'coffee shop', 0.8214959697396015 ],
//   [ 'wifi', 0.711907901740376 ],
//   [ 'hard work', 0.6709908415581982 ],
//   [ 'love peace & joy, relaxation', 0.6495931802131457 ]
// ]

(1 means it's exactly the same vector, -1 means it's exactly opposite, 0 means no correlation)

`embeddings` is a thin wrapper around gpt4all

lib/embeddings.js implements insertText which:

checks to see if these words are already in the DB
inserts them if they are not, with a batch update

The search function takes the query string and converts it to a vector, then runs a query with the vectra DB.

The specific model I'm using here is nomic-embed-text-v1.5 which is an open source model & free to use model that runs locally on your machine.

OpenAI embeddings

lib/embeddings-openai.js is a version of this file that has exactly the same API but sends the text to OpenAI. See OpenAI's embedding docs.

The OpenAI model captures more nuance in my experience (for example, it captures the semantic meaning of emojis whereas the open source one doesn't seem to).

Set the OPEN_API_KEY environment variable to use this. To run the example in example-openai-embedding/index.js:

pnpm openai-embedding

Clustering

To run example-clustering/index.js:

pnpm clustering

This clusters the vectors in the DB using k-means. You tell it the number of clusters you want to create, and it iterates over each point to find the "k nearest neighbors" to create these clusters.

Normally, you don't know how many clusters are in the data. There's various techniques to find this. One way is the "elbow method" where you cluster the dataset for increasingly higher cluster sizes and compute a "score". The score represents how close all items in the cluster are to a centroid. So the lower the score the more you end up with clusters of semantically related things.

I hope you found this useful! You can use the base code here to basically recreate Neal's Infinite Craft game. Basically put all the words in the dictionary in the vector database. Then to combine two words, add the vectors (or get the average?), then search for the closest thing to that combined vector.

This is my personal sandbox that I hope to add more stuff to. For example, there are models that can convert an image to a text description. You can then get a vector embedding for that text, and with that you can build an app where you can "CTRL+F" for your images (again, all offline, and free!)

Build & deploy your first web app

Omar — Fri, 14 Jul 2023 00:28:09 +0000

This guide is written for students going through CodeDay Labs. You will learn:

How to set up a simple web app from scratch
How to deploy your applications so others can access it via a URL

This tutorial is meant to teach the basic fundamentals of working with web technologies, regardless of what specific framework you might be using in the future.

Step 1 - Create an HTML page

We are going to create our first web page, by hand. You typically will not do this in your web development career, but it will help you understand what is happening under the hood, and what problems all these frameworks like React etc are trying to help you solve.

Create a new directory for our project. Name it web-dev-101
Open up your favorite code editor, like VSCode or Sublime Text, and create a new file called index.html
Copy/paste the following code:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Web Dev 101</title>
</head>
<body>
    <h1>Hello World!</h1>
</body>
</html>

Now preview your web page by double clicking on index.html, or dragging and dropping it into your web browser.

It should look like this:

Extra challenges:

What does the <h1> tag mean? What happens if you do <h2> tag instead? Or <p> tag?
Can you change the title in the browser tab, to make it say Web Dev 102 instead of Web Dev 101 ?

Step 2 - Add some styling / CSS

HTML is a markup language, it's for controlling what is shown on screen (as in, the content, the text, etc)

CSS is the styling language, it controls how things are displayed on screen (the color, the size, etc)

To add CSS/styling rules to your web page:

Add the following snippet inside the <head> tag:

    <style type="text/css">
        h1 {
            color: red;
        }
    </style>

It should go like this:

Then refresh your web page, the text should now be red:

This CSS rule we added makes ALL <h1> tags red. If we wanted to make a specific HTML element red, we have to give it either an ID or a class.

Give your <h1> element an id:

<h1 id="title">Hello World!</h1>

Change your CSS rule to target the element with the id title instead of all h1 tags:

#title {
  color: red;
}

The # symbol prefixing "title" is what tells CSS to apply the rule to any element that has the ID "title". This is called a CSS selector.

Another common type of CSS selector is a class. It works very similarly to an ID. You can give an element a class name as follows:

<h2 class="subtitle">My subtitle</h2>

And you can style it like this in CSS:

.subtitle {
  color: blue;
}

When should you use id vs class? Typically you use id for one specific element (like the title) and a class for something for which there can be multiple elements (like a paragraph, or a button).

Extra challenges:

What happens if you have an element that is BOTH an <h1> and has an id title, and you create a css rule that makes <h1> red and a css rule that makes title elements blue? Will the element be red or blue?
Can you use CSS to make an element underlined? Or bigger font?

Step 3 - Move your CSS to another file

You can add CSS into the same file as your HTML. But for bigger projects it is helpful to split it up into another file.

To do this:

Add the following line inside the <head> tag, this tells the HTML page it should load styles from a file called style.css:

<link rel="stylesheet" href="style.css">

Create a file called style.css and move your CSS in there. It might look like this:

Refresh the web page, confirm the CSS still works. Make a change to the style/color and confirm it updates when you refresh.

Step 4 - Deploy your web page

At this point the web page only exists on your computer. In order for others to access it on the internet, we need to:

Put it on a web server
Give it on a domain name

A "web server" is just a computer. Your personal laptop could be a web server. You just need to run a program that responds to HTTP requests and returns your web page.

In fact, let's try that real quick:

Install a simple http server library by running the following command:

npm install --global http-server

(if you don't already have npm installed, get it from here: https://nodejs.org/en/download. Yarn is also fine, the command might be slightly different.)

Open up a terminal window in the folder of your index.html and run the following command to run a web server on your laptop:

http-server .

The dot (.) tells it to serve the HTML files in the current directory.

This should give you an output that looks like this:

Available on:
  http://172.25.240.1:8080
  http://192.168.1.147:8080
  http://127.0.0.1:8080

Open up the second URL in your web browser (for me that's http://192.168.1.147:8080). You should see your website.
If it works, open up this URL on your phone or another computer. As long as it's connected to the same WiFi as your laptop, it should work.

What you just did is access your web page on your phone, powered by the web server running on your laptop!

You don't have a domain name, which is why you have to access it trough the IP address of your computer. It has to be on the same WiFi network for reasons outside the scope of this tutorial.

Step 5 - Deploy to a web server with a domain name

To put your web page on a server that others can access anywhere on the internet, we typically need to pay for this service. There's a few free options. One free option is: https://glitch.com/.

Create an account on https://glitch.com/signup
Create a new project (top right of the page)

Select the first option glitch-hello-website

This will take you to the Glitch code editor.

Copy paste your index.html from your computer into the Glitch editor (select index.html from the sidebar then just replace all its contents)
Do the same for style.css
Click the "Preview" button in the bottom panel to open up your website:

This is your website deployed to a web server, with a domain name you can now share!

Extra challenges:

Another option instead of using Glitch is using Github Pages. This is a way of automatically getting a deployed web page for any repository in your GitHub account.

The following guide will explain how to do it. Try to create a new repository for your web-dev-101 project and deploy it with GitHub pages:

https://pages.github.com/

Vite Hot Module Replacement - A Complete Example

Omar — Sun, 17 Apr 2022 15:45:21 +0000

This article explains how to set up hot module replacement (HMR) with Vite for a vanilla JS project. The goal is to be able to see changes in the code without refreshing or restarting the application.

For me this is particularly useful in creative coding when I'm iteratively building a simulation and don't want to lose state as I make live changes.

Complete source code for this article here: https://github.com/OmarShehata/vite-hot-reload-example.

Overview of my implementation

I'm going to show you how I've set up my HMR to make it as simple as possible to enable for new modules. In subsequent sections I'll break down how it works so you are aware of all the caveats and can use it in your project as needed.

To enable HMR on any module, I add the event handler at the top of the file:

import { HMREventHandler } from './HotModuleReloadSetup.js';

if (import.meta.hot) {
  import.meta.hot.accept(HMREventHandler)
}

This tells Vite to avoid refreshing the page when this module is updated, and instead fire an HMR event.

Next, I have a singleton instance of HotModuleReloadSetup that takes dynamically imported modules, and automatically swaps them out:

import HotModuleReloadSetup from './HotModuleReloadSetup.js';
// Setup HMR
const hmr = new HotModuleReloadSetup();
// Load a module that will be updated dynamically
hmr.import(await import('./Draw.js'));

I now have access to an instance of the Draw class through hmr.instances['Draw'].

Finally, the draw class defines a hotReload handler. This passes a reference to the old instance so you can copy over any state variables to the new instance.

So when I call hmr.instances['Draw'].draw() in the render loop, it will always use the latest code.

This pattern is modelled after how PlayCanvas does their hot reloading.

How it works

Here is what happens when you make a change in an HMR module (Draw.js in my case) & save the file:

1 - Vite triggers an HMR event (which we've added a listener to via import.meta.hot.accept)
2 - I then dispatch a custom event on the DOM with that new module (this is in HotModuleReloadSetup.js):

export function HMREventHandler(newModule) {
    const event = new CustomEvent('hot-module-reload', { detail: { newModule } });
    document.body.dispatchEvent(event);
}

This allows HotModuleReloadSetup to listen for these events globally.

3 - We search our map of modules to see if the new module we received exists
4 - If so, we create a new instance from the new module, call newInstance.hotReload(oldInstance), and discard the old module & old instance

swapModule(newModule) {
  const name = newModule.default.name;
  const oldModule = this.modules[name];
  const oldInstance = this.instances[name]
  if (!oldModule) return;

  const newInstance = new newModule.default();
  newInstance.hotReload(oldInstance)

  this.modules[name] = newModule
  this.instances[name] = newInstance
}

This way you can access either one instance of a class that is always updated through the instances map, or you can access the latest module through the modules map. The latter can be used if your code is spawning many instances of a class (like enemies or bullets), and you want your live code changes to affect newly spawned instances.

Caveats

If you need to have multiple instances of a class that are all updated when the code changes, you'll need to keep an array of these instances and swap them all out in the same way HotModuleReloadSetup.swapModule does
If your HMR class needs constructor arguments, you'll need to store those in the global manager that creates the new instances so they can be passed to them as well.
I turn off Rollup minification because it rewrites function names, but cannot update all uses of the function when using dynamic imports like this. That causes hmr.instances['Draw'].draw() to break because the function name is no longer draw in a production build.
I import the module by name and pass it to hmr.import() due to the limitations on dynamic imports in Vite, see: https://github.com/rollup/plugins/tree/master/packages/dynamic-import-vars#limitations

Thanks for reading! I hope you found this useful. If you find a bug or a better way to streamline HMR, especially for creative coding, I'd love to hear. You can find me on Twitter: https://twitter.com/omar4ur.

How to create bitmap fonts for Phaser JS with BMFont

Omar — Mon, 21 Feb 2022 12:55:21 +0000

This guide explains how to generate bitmap fonts from TTF or OTF files for use in PhaserJS. I'll be using BMFont which is Windows only.

Why bitmap fonts?

The main use case is if you're creating a pixel art game & want your text to match the retro style and have no antialiasing.

Below is an example from a recent game I made. The top is the standard font rendering in Phaser. The bottom is a bitmap version of the same font.

Note the antialiasing inside letters like g, a, or o in the top image. This creates what looks like blurry artifacts at the small scale of pixel art games. The bottom image has the crisp, pixelated rendering expected in retro games.

Bitmap fonts may also be faster to render. From the Phaser docs:

BitmapText objects are less flexible than Text objects, in that they have less features such as shadows, fills and the ability to use Web Fonts, however you trade this flexibility for rendering speed

To use a bitmap font, Phaser needs:

An image containing all the possible characters
An XML file that defines the x/y/width/height of each character in the image.

It's basically a spritesheet of letters.

Here's an example I generated from this public domain font: https://www.fontspace.com/public-pixel-font-f72305.

The image with all the letters:

Snippet from the XML:

<char id="32" x="507" y="0" width="3" height="1" xoffset="-1" yoffset="31" xadvance="32" page="0" chnl="15" />
<char id="33" x="285" y="87" width="18" height="28" xoffset="3" yoffset="4" xadvance="32" page="0" chnl="15" />
<char id="34" x="441" y="108" width="22" height="16" xoffset="3" yoffset="4" xadvance="32" page="0" chnl="15" />

You can download this generated example in the format that Phaser can use here: pixel_bitmap_font.zip

Step 1 - Download BMFont

Download the executable on this page:

https://www.angelcode.com/products/bmfont/

Step 2 - Load the font

Prepare your font as a TTF file or similar
Open up bmfont64.exe
Select Options > Font settings
Select your font file in Add font file
Then select the name of the font in the Font dropdown

If your font is installed system-wide you can skip the Add font file step and just select the name of the font directly.

Now you should see your font loaded:

Step 3 - Export

First, we change the export settings:

Select Options > Export options
Select XML as the Font descriptor
Select PNG as the textures option

Press OK

Then to export:

Select all letters for export (Ctrl + A)
File > Save bitmap font as

This will generate an XML file (it'll have the extension .fnt, you can rename that to .xml or leave it as-is, Phaser will be able to read it as an XML either way) and a PNG file.

You may need to increase the width/height in the export options to keep all the letters in one image.

Step 4 - Use it in Phaser

Tell Phaser where to load the PNG & XML files:

// Load it
this.load.bitmapFont('bitmapFontName', 'font.png', 'font.fnt');
// Add it to the scene
this.add.bitmapText(0, 0, 'bitmapFontName', 'Lorem ipsum\ndolor sit amet');

Full example here: https://labs.phaser.io/edit.html?src=src/loader/bitmap%20text/load%20bitmap%20text.js.

Final thoughts

Note that a generated bitmap font has a font size baked in. Phaser can scale the font up and down but that may introduce artifacts in some cases. If you know the font size you want ahead of time you can set it in Options > Font settings.

I used a font size of 32px in my game which was big enough so that it still looked good when scaled down or up a bit.

I hope you found this useful! If you have any corrections or find a better way to generate bitmap fonts for Phaser I'm happy to update this article. Find me on Twitter (@Omar4ur) or my website (https://omarshehata.me/).

Create a satellite tracker from scratch in 30 lines of JavaScript

Omar — Thu, 06 May 2021 02:32:25 +0000

This tutorial will walk you through how to create a web app that visualizes the location of any satellite in real-time, like the International Space Station.

We're going to do this from scratch, using the same techniques a real rocket scientist would!

We'll look at where to get the data about individual satellites that the government publishes, known as Two-Line Element Sets, or TLE's.
We'll use satellite-js to predict the orbit of the satellite given the TLE's (this is the rocket science part).
We'll use CesiumJS to visualize the result, but you can use any library/engine that can take in longitude, latitude, and height.

Below is a preview of the final result.

This is showing the path of the International Space Station, sped up by 40x. To see its current location in real-time, click the clock icon at the top-left of the clock wheel.

Here's a direct link to the app. And the source code on Glitch.

1 - Get the satellite's Two-Line Element Set

A Two-Line Element Set, or TLE, is a data format that describes the motion of an object orbiting the Earth. It was created by the North American Aerospace Defense Command (NORAD). You can read more about it and its history here.

Given this description of the orbit, we can predict the location of where it's going to be at any moment in time (which is step 2 below).

This means that most "live" satellite trackers are not live in the same way that tracking a delivery car on a map is. Instead of relying on constantly receiving position updates, those who track objects in space will often get the latest TLE's (which are regularly updated) and use that to predict where the object is right now.

Where do we get the TLE's? There is no one global official registry. Whoever owns the satellite and is monitoring it is responsible for updating and publishing the TLE for the benefit of the global space community (unless it's a spy satellite).

We can find these TLE's on Space Track which is a registry run by the United States Space Command.

Another source is this list on CeleStrak maintained by Dr. T.S. Kelso.

We're going to use CeleStrak since it doesn't require a login. To find the TLE for the International Space Station, click on the Space Stations link.

The first one is the TLE for the ISS:

ISS (ZARYA)             
1 25544U 98067A   21122.75616700  .00027980  00000-0  51432-3 0  9994
2 25544  51.6442 207.4449 0002769 310.1189 193.6568 15.48993527281553

The meaning of these numbers is listed in table 1 in Dr T.S. Kelso's column. Most of them are identifiers and metadata about the satellite, like when it was launched.

You can find TLE's for weather satellites, GPS satellites, and even SpaceX's Starlink constellation in this same format.

2 - Predict the satellite orbit

Now that you know how to get the TLE of the object you're interested in tracking, the next step is converting that to a position in time.

We're going to use satellite-js for this.

Include the library from a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/satellite.js/4.0.0/satellite.min.js"></script>

Then pass the TLE to it, and a time:

const ISS_TLE = 
    `1 25544U 98067A   21122.75616700  .00027980  00000-0  51432-3 0  9994
     2 25544  51.6442 207.4449 0002769 310.1189 193.6568 15.48993527281553`;
// Initialize the satellite record with this TLE
const satrec = satellite.twoline2satrec(
  ISS_TLE.split('\n')[0].trim(), 
  ISS_TLE.split('\n')[1].trim()
);
// Get the position of the satellite at the given date
const date = new Date();
const positionAndVelocity = satellite.propagate(satrec, date);
const gmst = satellite.gstime(date);
const position = satellite.eciToGeodetic(positionAndVelocity.position, gmst);

console.log(position.longitude);// in radians
console.log(position.latitude);// in radians
console.log(position.height);// in km

Now we have the position of the satellite at the current time, new Date().

This position is produced as a result of simulating a specific model of satellite motion. This model is called SGP4/SDP4. All TLE's assume this specific model.

If you're wondering about the accuracy of this model, the short answer is, it depends.

Accuracy of the two-line element sets is dependent upon a number of factors. These range from the particular sensors used and amount of data collected to the type of orbit and condition of the space environment. Unfortunately, since these factors vary for each element set, so does the accuracy. While NORAD has experimented with methods to incorporate prediction quality into the element sets, none of these methods has yet proved successful.

3 - Visualize the result

Now we have a way to get the location of any satellite, at any given time. We can pass in future times to animate its path, which we'll do in the next step.

First, let's see how to visualize an individual point in space using CesiumJS.

We load the library from CDN:

<script src="https://cesium.com/downloads/cesiumjs/releases/1.81/Build/Cesium/Cesium.js"></script>
  <link href="https://cesium.com/downloads/cesiumjs/releases/1.81/Build/Cesium/Widgets/widgets.css" rel="stylesheet">

And create a container element:

<div id="cesiumContainer"></div>

We then initialize the viewer. Here we pass in some extra options to disable functionality that requires an access token:

// Initialize the Cesium viewer.
const viewer = new Cesium.Viewer('cesiumContainer', {
  imageryProvider: new Cesium.TileMapServiceImageryProvider({
    url: Cesium.buildModuleUrl("Assets/Textures/NaturalEarthII"),
  }),
  baseLayerPicker: false, geocoder: false, homeButton: false, infoBox: false,
  navigationHelpButton: false, sceneModePicker: false
});
viewer.scene.globe.enableLighting = true;

Finally, we'll visualize the satellite position as a red dot in space:

const satellitePoint = viewer.entities.add({
  position: Cesium.Cartesian3.fromRadians(
    position.longitude, position.latitude, position.height * 1000
  ),
  point: { pixelSize: 5, color: Cesium.Color.RED }
});

See the complete source code of this step in simple.html on Glitch.

4 - Animate the path

To animate the path, we just need to sample more positions in the future. CesiumJS has a built-in way to interpolate between these samples over time.

The setup for this is a bit verbose. You can see the full code on Glitch. The important concepts are described below.

We create a SampledPositionProperty. This is an object that will hold position samples over time and will interpolate between them:

const positionsOverTime = new Cesium.SampledPositionProperty();

We loop through however many samples we want to get, and for each sample, we construct a time object, called JulianDate in CesiumJS, and a position, and we add that as a sample:

for (let i = 0; i < totalSeconds; i+= timestepInSeconds) {
  const time = Cesium.JulianDate.addSeconds(start, i, new Cesium.JulianDate());
  // ...Get position from satellite-js...
  const position = Cesium.Cartesian3.fromRadians(p.longitude, p.latitude, p.height * 1000);
  positionsOverTime.addSample(time, position);
}

Finally, we pass this positionsOverTime object to our point.

const satellitePoint = viewer.entities.add({
  position: positionsOverTime,
  point: { pixelSize: 5, color: Cesium.Color.RED }
});

The point will move as the timeline at the bottom moves. To attach the camera to the moving point we do:

viewer.trackedEntity = satellitePoint;

Conclusion

I hope you enjoyed learning a little bit about what goes into building a satellite tracker. There's a lot more to the topic we didn't touch on, like what exactly do the parameters in the TLE mean? How often are they updated? How are they updated?

I don't know, but I find it really empowering to know what formats this kind of data is published in & where to get it, and quite amazing that we can do all this directly in the browser with JavaScript!

Here's a couple fun ideas to explore now that we can do this:

Visualize multiple satellites, like the entire Starlink constellation. Inspired by Celestrak's viewer which shows every satellite in its catalog. Perhaps visualize how the number of Starlink satellites grew over time?

Or simulate what it would look from street level. Maybe add buildings/elevation data to find the best place in the city to see the satellite?

There's a prototype of this in street-level.html in the Glitch source code. Demo: https://satellite-viewer.glitch.me/street-level.html.

See also James Darpinian's "See a satellite tonight" app which uses a combination of CesiumJS and Google street view.

It might also be fun to use a 3D model of the right scale instead of a dot, and get a real sense of how close satellites get to each other in space.

How to load Sketchfab models directly in a ThreeJS app

Omar — Wed, 28 Apr 2021 01:34:15 +0000

Sketchfab's API gives you programmatic access to the largest collection of glTF 3D models on the web. This article walks you through a minimal code example to show you how to:

Let your users authenticate with the Sketchfab API
Download a 3D model as a zip file containing the glTF
Load this zip file into ThreeJS

Source code: https://github.com/OmarShehata/threejs-sketchfab-example

How it works

I originally implemented this to let readers of my WebGL outlines tutorial see how the effect looked on test cases of their choosing. Since I kept finding algorithms that didn't work on my specific corner cases (but I wouldn't find out until after I implemented it/downloaded & ran it!)

It's a really easy way to let users bring in their own data (or millions of example models).

You can see how this works in this outlines live demo:

Open the demo: https://omarshehata.github.io/csb-l01dp/
Click Login to Sketchfab
When directed back to the app, paste a link of a model in the Sketchfab URL field, like this: https://sketchfab.com/3d-models/skull-downloadable-1a9db900738d44298b0bc59f68123393

The model must be downloadable by the Sketchfab account that's logged in.

1 - Authenticate with the Sketchfab API

The first step is to register your app with Sketchfab. The instructions for this are here:

https://sketchfab.com/developers/oauth#registering-your-app

The current process at the time of writing is to contact them.

You'll need to pick a redirect URI. This should be the final URI where you will deploy your app.

You'll want to use the Implicit grant type. We can't keep an API key a secret in a web app, so we instead rely on the redirect URI (if someone malicious uses your client ID, Sketchfab will redirect them to your real app after login, regardless of who may have initiated the login).

After your register your app you'll have a Client ID.
You'll use this to send the user to Sketchfab for login as shown here:

const CLIENT_ID = 'YOUR_CLIENT_ID_HERE';
const AUTHENTICATION_URL = `https://sketchfab.com/oauth2/authorize/?state=123456789&response_type=token&client_id=${CLIENT_ID}`;
window.open(AUTHENTICATION_URL, '_blank');

Once the login is done, you'll need to grab the access token from the URL. Here's a snippet that does this and stores it in local storage here:

checkToken() {
    // Check if there's a new token from the URL
    const url = new URL(window.location)
    // Extract the token and save it
    const hashParams = url.hash.split('&');
    for (let param of hashParams) {
        if (param.indexOf("access_token") !== -1) {
            const token = param.replace('#access_token=', '');
            console.log("Detected Sketchfab token: ", token);
            localStorage.setItem("sb_token", token);
        }
    }

    // Load token from local storage
    this.token = localStorage.getItem("sb_token");
}

Source code on GitHub.

You'll use this token for subsequent API calls.

Note: while you're developing locally, Sketchfab will redirect to the production URI. You'll need to copy the URI params to your localhost to test.

2 - Download the 3D model

Once you have a token, you can use this to fetch a download URI for the glTF model.

Here is the code snippet for fetching the download URI given any Sketchfab URI like this: https://sketchfab.com/3d-models/skull-downloadable-1a9db900738d44298b0bc59f68123393

async getModelDownloadUrl(inputUrl) {
    // Extract the model ID from the URL
    const input = new URL(inputUrl);
    // The ID is always the last string when seperating by '-'
    const pieces = input.pathname.split('-');
    const modelID = pieces[pieces.length - 1];

    const metadataUrl = `https://api.sketchfab.com/v3/models/${modelID}/download`;
    const options = {
        method: 'GET',
        headers: {
            Authorization: `Bearer ${this.token}`,
        },
        mode: 'cors'
    };

    // This call will fail if model can't be downloaded
    const response = await fetch(metadataUrl, options);
    const metadata = await response.json();
    return metadata.gltf.url;
}

Source code on GitHub.

Note that this request will fail if the user who is logged in does not have access to download this model. This will be true for store models that require a purchase, or free models that are not downloadable.

You can filter for downloadable models in the Sketchfab search:

This will show you either free models you can download or models that can be purchased.

Now that we have a URL to a zip file containing a glTF model, we can pass that to ThreeJS to load it.

3 - Load the ZIP file into ThreeJS

This was the tricky part of me. Normally ThreeJS requires a direct URL to the glTF file. To load it from a zip file we're going to (1) unzip the contents into memory using JSZip.

We can't just pass the unzipped raw content to ThreeJS, because a glTF file may reference other files by a filepath (image or geometry resources). So we need to (2) create a Blob for each resource and (3) override the resources the glTF file is requesting with the Blob URI's.

For example, if the glTF file is trying to load textures/defaultMat_baseColor.jpeg as a relative filepath, we detect this, and instead pass this URI:

//Unzip from JSZip
const file = unzippedBaseColorJPEGFile;
// Create a Blob from this file
const blob = await file.async('blob');
// Create a URL to this Blob
const baseColorBlobUrl = URL.createObjectURL(blob);
// Use ThreeJS's loading manager so instead of loading from relative filepaths we load from the blob URI's we created
const loadingManager = new THREE.LoadingManager();                            loadingManager.setURLModifier((url) => {
  if (url == 'textures/defaultMat_baseColor.jpeg') {
    return baseColorBlobUrl;
  }
});

We use ThreeJS's LoadingManager to do this.

Here is the code snippet that can take a URL to any zipped glTF and load it in ThreeJS:

async readZip(zipUrl, scene) {
    const response = await fetch(zipUrl);
    checkStatus(response);
    const arrayBuffer = await response.arrayBuffer();

    const result = await JSZip.loadAsync(arrayBuffer);

    const files = Object.values(result.files).filter(item => !item.dir);
    const entryFile = files.find(f => getExtension(f.name) === 'gltf');
    // Create blobs for every file resource
    const blobUrls = {};
    for (const file of files) {
        console.log(`Loading ${file.name}...`);
        blobUrls[file.name] = await getFileUrl(file);
    }
    const fileUrl = blobUrls[entryFile.name];

    scene.clear();
    // Re-add the light
    const light = new THREE.DirectionalLight(0xffffff, 1);
    scene.add(light);
    light.position.set(1.7, 1, -1);

    const loadingManager = new THREE.LoadingManager();
    loadingManager.setURLModifier((url) => {
        const parsedUrl = new URL(url);
        const origin = parsedUrl.origin;
        const path = parsedUrl.pathname;
        const relativeUrl = path.replace(origin + '/', "");

        if (blobUrls[relativeUrl] != undefined) {
            return blobUrls[relativeUrl];
        }

        return url
    });
    const gltfLoader = new GLTFLoader(loadingManager);
    gltfLoader.load(fileUrl, (gltf) => {
      scene.add(gltf.scene);
    });
}

Source code on GitHub.

4 - Display attribution

Using 3D models from Sketchfab in your application requires that you display attribution to the original author. Read more about this on Sketchfab.

We can automatically get the attribution & license information from this Data API route.

Here is a function that will construct the attribution text given a modelID:

async getAttributionText(modelID) {
        const modelDataUrl = `https://api.sketchfab.com/v3/models/${modelID}`;
        const options = {
            method: 'GET',
            headers: {
                Authorization: `Bearer ${this.token}`,
            },
            mode: 'cors'
        };
        const response = await fetch(modelDataUrl, options);
        const metadata = await response.json();

        const license = { name: metadata.license.label, url: metadata.license.url };
        const user = { name: metadata.user.displayName , url: metadata.user.profileUrl };
        const model = { name: metadata.name, url: metadata.viewerUrl };
        const attributionText = 
        `This work is based on <a href="${model.url}" target=_blank>${model.name}</a>
        by <a href="${user.url}" target=_blank>${user.name}</a> 
        licensed under <a href="${license.url}" target=_blank>${license.name}</a>.`;

        return attributionText;
    }

Source code on GitHub.

The example app will display the attribution in the bottom left corner, linking to the original model URL, author's Sketchfab profile, and the license.

Known issues

One problem with loading some Sketchfab models is that their scale will be much bigger than the current viewport. Another problem is some models may not be centered around the origin, so they may not be visible when loaded.

Normalizing and scaling models when loading them in ThreeJS would help solve this, similar to how Don McCurdy's glTF Viewer works.

Thanks for reading! If you found this helpful, follow me on Twitter @omar4ur to see more of my work. Other ways to reach me at https://omarshehata.me/.

Forem: Omar

Handmade GitHub Pages

Handmade Cellular Automata

Inspirations

Overview of the series

1. Install VS Studio Code

2. Create an HTML file

3. Deploy your code on the internet

4. Animated rectangle

5. Cellular Automata Grid

Open source semantic embedding, search & clustering in NodeJS

Setup

embeddings is a thin wrapper around gpt4all

OpenAI embeddings

Clustering

Build & deploy your first web app

Step 1 - Create an HTML page

Extra challenges:

Step 2 - Add some styling / CSS

Extra challenges:

Step 3 - Move your CSS to another file

Step 4 - Deploy your web page

Step 5 - Deploy to a web server with a domain name

Extra challenges:

Vite Hot Module Replacement - A Complete Example

Overview of my implementation

How it works

Caveats

How to create bitmap fonts for Phaser JS with BMFont

Why bitmap fonts?

Step 1 - Download BMFont

Step 2 - Load the font

Step 3 - Export

Step 4 - Use it in Phaser

Final thoughts

Create a satellite tracker from scratch in 30 lines of JavaScript

1 - Get the satellite's Two-Line Element Set

2 - Predict the satellite orbit

3 - Visualize the result

4 - Animate the path

Conclusion

How to load Sketchfab models directly in a ThreeJS app

How it works

1 - Authenticate with the Sketchfab API

2 - Download the 3D model

3 - Load the ZIP file into ThreeJS

4 - Display attribution

Known issues

`embeddings` is a thin wrapper around gpt4all