Intro

I've been building this blog from the ground up, and with the intent of eventually open sourcing it as a template. This post is a test post/playground where I test and showcase the different features of the blog.

A quick word about the stack

This blog is built with Next.js. Styling is done with Tailwind CSS. The blog posts are written in MDX, a flavour of Markdown that allows you to embed React components.

A quick word about the design

I attempted to prioritize beautiful typesetting. There are three typefaces used on this blog: IBM Plex Sans for UI elements and headers, Literata for body text (I prefer serif fonts for long form reading), and <a style={{fontFamily: "Twilio Sans Mono"}} href="https://www.twilio.com/blog/power-up-your-code-with-twilio-sans">Twilio Sans Mono for code blocks.

Post Features

Post settings are set in the frontmatter of the post. Here's the frontmatter for this post:

---
title: "Blog Features"
description: "This is a test post to showcase the different components of this blog."
date: "2022-08-01T12:24:13.637Z"
topics: ["Meta"]
hero: "/images/david.jpg"
published: true
toc: true
type: "post"
---

Table of Contents

To display the table of contents on the left side of the page, add toc: true to the frontmatter of your post. Note, that the table of contents only displays h2 and h3 headers, i.e. ## and ###. h1 reserved for the title of the post.

Hero image

To display a hero image at the top of the page, add hero: "/path/to/image" to the frontmatter of your post.

Draft posts

If you do not wish to publish a post yet, add published: false to the frontmatter of your post.

General Features

Code view

The code blocks are rendered using a slightly modified rehype-pretty-code plugin.

{/* prettier-ignore */}

```javascript title="Add two numbers" {2}
const add(a, b) => {
  return a + b;
}
```

Output

const add(a, b) => {
  return a + b;
}

Mathematical equations

Mathematical equations are rendered using $\KaTeX$. Use $ for inline equations and $$ for display equations.

If $x^2 + y^2 = 1$, then $y = \sqrt{1 - x^2}$.

In other words,

$$
\begin{align*}
x^2 + y^2 &= 1 \\
y &= \sqrt{1 - x^2}
\end{align*}
$$

Output

If $x^2 + y^2 = 1$, then $y = \sqrt{1 - x^2}$.

In other words,

$$
\begin{align*}
x^2 + y^2 &= 1 \
y &= \sqrt{1 - x^2}
\end{align*}
$$

Images

Place images in /public/images. You can include them in your post like this:

![This will be the image caption](/images/spirited_away.jpg)

Output

This will be the image caption

Footnotes

You can use footnotes as follows:

According to this study[^1], the...

[^1]: Smith, John. "The Effects of Artificial Intelligence on Society." Journal of Futuristic Technology 14.2 (2022): 45-61. Print.

Output

According to this study[^1], the...

[^1]: Smith, John. "The Effects of Artificial Intelligence on Society." Journal of Futuristic Technology 14.2 (2022): 45-61. Print.

MDX Components

Alert boxes

Exclamation

<Alert type="exclamation" title="Info">
  Please make sure you have backups before attempting this procedure.
</Alert>

Output

Warning

<Alert type="warning" title="Read carefully">
  Watch out for any errors or typos.
</Alert>

Output

Info

<Alert type="info" title="Read carefully">
  Watch out for any errors or typos.
</Alert>

Output

Info (no color)

<Alert type="normal" title="Read carefully">
  Watch out for any errors or typos.
</Alert>

Output

Collapsible section

<Collapsible title="Quadratic equation" open={true}>
A quadratic equation is an equation that can be written as $ax^2 + bx + c = 0$, where $a \neq 0$.

The general formula used to solve the roots of a quadratic equation is

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}.
$$
</Collapsible>

Output

The general formula used to solve the roots of a quadratic equation is

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}.
$$

Links

You can use styled link components to display links.

<Linked href="https://example.com">Visit example.com</Linked>
<Download href="https://example.com">Download example files (.zip)</Download>

Output

Visit example.com
Download example files (.zip)

Bordered area

You can create a bordered area for styled text.

{/* prettier-ignore */}

<BorderedArea>
###### **synchronicity | ˌsiNGkrəˈnisədē |**
<span className="font-sans">noun</span>
1. the simultaneous occurrence of events which appear significantly related but have no discernible causal connection: such synchronicity is quite staggering.
2. another term for synchrony (sense 1).
</BorderedArea>

Output

{/* prettier-ignore */}


synchronicity | ˌsiNGkrəˈnisədē |

noun

the simultaneous occurrence of events which appear significantly related but have no discernible causal connection: such synchronicity is quite staggering.
another term for synchrony (sense 1).

YouTube

You can embed YouTube videos using the YouTube component. id is the ID of the video, i.e. the part after v= in the URL. title is the title of the video, which is used as the title attribute of the iframe.

<YouTube title="Wintergatan – Marble Machine" id="IvUU8joBb1Q" />

Output

Tweets

You can create hardcoded Tweets. Although it takes a bit of effort to create one, the benefit is that it's served as static HTML, i.e. no Twitter trackers are loaded, and it stays up even if the original Tweet is deleted. Idea from Josh Comeau.

Code

{/* prettier-ignore */}

<Tweet
  user="Macaulay Culkin"
  username="@IncredibleCulk"
  verified="true"
  avatarurl="https://pbs.twimg.com/profile_images/968572702788239360/KL-zulbA_400x400.jpg"
  date="2020-08-27T12:13:00.000Z"
  comments="55,351"
  retweets="403,524"
  likes="2M"
  userurl="https://twitter.com/IncredibleCulk"
  tweetUrl="https://twitter.com/IncredibleCulk/status/1298730289737293824"
>
  Hey guys, wanna feel old?
  
  I'm 40.
  
  You're welcome.
</Tweet>

Output

{/* prettier-ignore */}
<Tweet
  user="Macaulay Culkin"
  username="@IncredibleCulk"
  verified="true"
  avatarurl="https://pbs.twimg.com/profile_images/968572702788239360/KL-zulbA_400x400.jpg"
  date="2020-08-27T12:13:00.000Z"
  comments="55,351"
  retweets="403,524"
  likes="2M"
  userurl="https://twitter.com/IncredibleCulk"
  tweetUrl="https://twitter.com/IncredibleCulk/status/1298730289737293824"



  Hey guys, wanna feel old?

  I'm 40.

  You're welcome.


Sidenotes

Tufte-style sidenotes. On desktop, they will be shown on the right, on smaller screens they are displayed within the text.

Code

{/* prettier-ignore */}

Laboris anim commodo duis duis officia<Sidenote>This is a sidenote.
On desktop, it will be shown on the right, on mobile it is displayed
within the text.</Sidenote> anim excepteur sit exercitation
consectetur velit et laboris nostrud magna.

Output

Laboris anim commodo duis duis officiaThis is a sidenote. On desktop, it will be shown on the right, on smaller screens it is displayed within the text. anim excepteur sit exercitation consectetur velit et laboris nostrud magna.

References

This is a post to test and showcase the different components of this blog.

Blog Features

The Problem

The puzzle was originally mentioned in this video by Matt Parker.

The goal is to find a set of five five-letter words that have twenty-five unique letters. I thought the puzzle was interesting enough to try to solve it myself, but when Parker said that his solution took a whopping 31.95 days to compute, I got nerd sniped. There has got to be a faster way!

Parker used a word list of ~340,000 English wordsWhile this list does not include every word, it is good enough for this purpose.. As seen in the video, some of the words in the word list were questionable at best. There were words such as FLDXT, HDQRS, EXPWY, (short for fluid extraxt, headquarters, and expressway). Due to this, Parker later decided to use the word list of Wordle as an authoritative source of proper words. I will be using the original word list of 340,000 words.

My Solution

My solution is JavaScript-based (full code in the Appendix). I first downloaded the same word list that Parker used, and loaded it into a JavaScript array. The first step is to filter out all words that are not five letters long. Next, any words that have duplicate characters in them, e.g. CLASS, need to be filtered out as well, as they break the rules of the puzzle.

const fs = require("fs");

// Read the word list into an array
let words = fs.readFileSync("words-alpha.txt", "utf8").split("\n");

// Remove all characters that are not 5 letters long
words = words.filter((word) => word.length === 5);

// Remove words that have duplicate characters
words = words.filter((word) => new Set(word).size === word.length);

To make the algorithm run faster, a couple of things can be optimized here. The first optimization idea is to remove redundant anagram words, as Parker did in the video. The word list contains multiple anagrams, e.g. study is equivalent to dusty in terms of characters used. Duplicate anagram words can be removed by creating an index, where each word is transformed by sorting its letters in an alphabetical order. For example, the word SLATE becomes AELST, etc. These sorted will be used to find all anagram words. For example, dusty will have the same index as study (dstuy).

The original length of the word list was 12,972 five-letter words. After removing all words with duplicate characters, and redundant anagram words, the length of the word list was reduced to 5,182. This will already make the task a bit faster to solve.

The second optimization idea is to represent the words as bitsets. As there are only 26 letters in the English alphabet, we can think of each letter as a number between 0 and 25, a to z. Bitset operations are significantly faster than string operations. For example, instead of checking if two strings share common characters by iterating through every character in both strings, we can now simply check if the two bitsets intersect. For bitset operations, I used the FastBitSet.js library.

const FastBitSet = require("fastbitset");

const wordIndex = [];

const stringToNumberArray = (s) => {
  const arr = [];
  for (const char of s) {
    arr.push(char.charCodeAt(0) - 97);
  }
  return arr;
};

for (const word of words) {
  wordIndex.push({
    word,
    index: word.split("").sort().join(""),
    bitIndex: new FastBitSet(stringToNumberArray(word)),
  });
}

const indexValues = wordIndex.map((word) => word.index);
const indexSet = [...new Set(indexValues)];

const uniqueIndex = [];

for (const word of wordIndex) {
  if (
    indexSet.includes(word.index) &&
    !uniqueIndex.find((item) => item.index === word.index)
  ) {
    uniqueIndex.push(word);
  }
}

The Algorithm

A recursion-based algorithm is used to find any possible sequences.

// Filter out words from the index that have common characters with the sequence
const filterIndex = (sequence, index) => {
  return index.filter((item) => {
    const itemIDX = item.bitIndex;
    return !itemIDX.intersects(sequence.bitIndex);
  });
};

const findWords = (sequence, index) => {
  if (sequence.word.length === 25) {
    foundSequences.push(sequence.word);
  }

  const searchSpace = filterIndex(sequence, index);

  for (let i = 0; i < searchSpace.length; i++) {
    findWords(
      {
        word: sequence.word + searchSpace[i].word,
        bitIndex: sequence.bitIndex.new_union(searchSpace[i].bitIndex),
      },
      searchSpace.slice(i + 1)
    );
  }
};

for (let i = 0; i < uniqueIndex.length; i++) {
  console.log(`${i + 1}/${uniqueIndex.length}`);
  findWords(uniqueIndex[i], uniqueIndex.slice(i + 1));
}

The algorithm iterates through every word in uniqueIndex. For each word, it calls findWords, a recursive function that finds any valid sequences recursively. findWords takes two parameters: the current sequence of words, and the remaining words in the index. The slice method is used to remove the current – and already-tried words from the index, as there is no need to try them again with other combinations.

At each step, findWords filters the remaining words in the index by removing any words that have common characters with the current sequence by using the filterIndex function. filterIndex checks if the bitset of the sequence and the bitset of the word interset. If they do, they share common bits, that is, letters.

If the length of the sequence gets to 25, a valid sequence has been discovered. Valid sequences are added to the foundSequences array.

Benchmark

My solution took 53.6 seconds to run on a 2018 MacBook Pro. All in all, 538 unique sequences were found (including fjord – gucks – nymph – vibex – waltz that Parker found in the video). However, it is worth pointing out that due to the removal of anagram words, there exist more than 538 unique sequences. However, it is trivial to recover these missing sequences, as we still have the original wordIndex that has not been filtered.

Comparing this to the original running time of 31.95 days, the importance of optimization becomes evident.

Appendix

Project files (.zip)

Execute the code by running the following commands in the terminal.

npm install
node index.js

My “giving-it-a-go” on an a puzzle by Matt Parker.

Five Five-letter Words with Twenty-Five Unique Letters

Project Links

API documentation

The API is currently deployed at https://chess-scanner.sumi.re, and is free to use. Please do not abuse it.

Intro

I enjoy watching chess content on YouTube. Sometimes I see an interesting position in a video, and wish to try my own variations. Now, how can I open the same position in Lichess' analysis tool or Stockfish? I could install a browser extension like Chessvision.ai, but where would the fun be in that?
In this post I'll outline how to train your own chess position detector.

The Idea

As an input, the program receives a cropped image of a chessboard.
The image is evenly divided into an 8×8 grid, i.e. each cell is one square on the chessboard.
A multiclass classifier is run on each square, determining the piece (if any), on that square.
From this, a chessboard is constructed, and the position is returned as a FEN string, which can then be pasted into any chess analysis tool.

As there are 64 squares on the board, the classifier needs to be extremely accurate. A classifier that is 99% accurate is not enough, as the probability that it will correctly classify all 64 squares is only $0.99^{64} \approx 53%$.

Step 1: The Data

It's easy to think that all chess pieces look pretty much the same, but there's actually a wide variety of different piece set designs, even in digital chessboards. In order for the model to be able to generalize, it must be trained on various piece sets and boards.
Since Lichess and Chess.com are the most popular online chess websites, I decided to use their boards and piece sets for training.

White knights in various styles.

Instead of creating a predetermined number of training and testing images, I decided to generate them on the fly. This gives us several advantages:

We can generate an almost endless amount of training data with random piece sets and boards, without having to store it on disk.
We can also do data augmentation on the fly.
We can control the distributions of the training data, e.g. the proportion of empty squares.
The model is less likely to overfit due to regularization from the data augmentation and randomness of the training data.

Let's first read the images of the pieces and boards into lists.
training.zip contains two folders, boards and pieces. boards has 45 PNG images of the pieces of a particular set. The naming follows the convention <piece>_<color>.png, where <piece> is one of k, q, r, b, n, or p, and <color> is either w for white or b for black.

import cv2
import numpy as np
import glob
import os

tile_images = []
piece_images = []

n_boards = 45
n_piece_sets = 59

# Make sure board_size is a multiple of 8
board_size = 400
square_size = int(board_size / 8)

# Process boards
for i in range(1, n_boards + 1):
  img = cv2.imread(f"boards/{i}.png")
  img = cv2.resize(img, (board_size, board_size), fx=0.5, fy=0.5, interpolation=cv2.INTER_AREA)

  # Iterate over each 50×50 square on the board
  for n in range(8):
      for m in range(8):
          square = img[n * square_size : (n + 1) * square_size, m * square_size : (m + 1) * square_size]
          # Append as [label, image]
          tile_images.append(["empty", square.flatten()])

# Process pieces
for i in range(1, n_piece_sets + 1):
  pieces = glob.glob(f"pieces/{i}/*.png")

  for piece in pieces:
    piece_type = piece.split("/")[-1].split(".")[0].split("_")[0]
    piece_color = piece.split("/")[-1].split(".")[0].split("_")[1]

    if piece_color == "w":
      piece_type = piece_type.upper()

    img = cv2.imread(piece, cv2.IMREAD_UNCHANGED)
    img = cv2.resize(img, (square_size, square_size), fx=0.5, fy=0.5, interpolation=cv2.INTER_AREA)

    piece_images.append([piece_type, img.flatten()])


tile_images = np.array(tile_images, dtype=object)
piece_images = np.array(piece_images, dtype=object)

We resize the boards to 400×400 pixels, which means that each trainable square is going to be 50×50 pixels in size.

For each board, we iterate over each square, extract it, and add it to the tile_images list. We also add the label empty, to indicate an empty square.

As the pieces are transparent PNG images, we need to use the option cv2.IMREAD_UNCHANGED, when reading the image. Otherwise the alpha channel will be stripped, and we cannot overlay the pieces on top of the board images. Similarly, we read all the piece images, resize them and add them to the piece_images list with their respective labels.

The reason why we separated the board and piece images into two separate lists is because we want to control the amount of empty squares in our dataset. On a chessboard, there can be no more than 32 pieces on the board at a time (16 white, 16 black, no captures), meaning that given any position, the number of empty squares is greater than or equal to the number of non-empty squares. When generating the training data, the proportion of empty squares in the data was set to 50%.

Now we can create a function that generates random chessboard pieces on the fly.

import random

def get_sample(empty_prop, augmentation=True):
  tile = random.choice(tile_images)[1].reshape(square_size, square_size, 3)

  if random.random() < empty_prop:
    return tile / 255.0, "empty"
  else:
    piece = random.choice(piece_images)
    piece_label = piece[0]
    piece_image = piece[1].reshape(square_size, square_size, 4)

    piece_alpha = piece_image[:,:,3]
    alpha = cv2.merge([piece_alpha, piece_alpha, piece_alpha])
    piece_image = piece_image[:,:,0:3]
    blend = np.where(alpha==(0,0,0), tile, piece_image)

    if augmentation:
      if random.random() < 0.2:
          blur_amount = random.choice([1, 3, 5])
          blend = cv2.GaussianBlur(blend, (blur_amount, blur_amount), 0)

      if random.random() < 0.5:
          shift_amount = random.choice([1, 2, 3, 4, 5])
          shift_direction = random.choice([-1, 1])
          shift_axis = random.choice([0, 1])
          blend = np.roll(blend, shift_amount * shift_direction, axis=shift_axis)

      if random.random() < 0.10:
        angle = random.choice([-2, -1, 1, 2])
        image_center = tuple(np.array(blend.shape[1::-1]) / 2)
        rot_mat = cv2.getRotationMatrix2D(image_center, angle, 1.0)
        blend = cv2.warpAffine(blend, rot_mat, blend.shape[1::-1], flags=cv2.INTER_LINEAR)

    return blend / 255.0, piece_label

The get_sample function is used to generate a single training image. The argument empty_prop is the probability that the square will be empty. The function returns a 50×50 image and its corresponding label. It first selects a random image of an empty square. Then, depending on the value of empty_prop and randomness, it either returns the empty square image, or it overlays a random piece on top of it. If augmenation is set to True, some random transformations may be applied to the image. The images can be slightly blurred, shifted, or rotated. All samples are normalized to the range $[0, 1]$.

Below is a sampled collection of 1200 randomly generated chessboard squares. The probability of an empty square was set to 0.5.

1200 randomly generated chessboard squares.

Next, we can create a function that generates a batch of training data for the model.

piece_labels = ["empty", "k", "q", "r", "b", "n", "p", "K", "Q", "R", "B", "N", "P"]

def generate_batch(batch_size, empty_prop):
  batch = []
  labels = []
  for i in range(batch_size):
    sample = get_sample(empty_prop)
    batch.append(sample[0])
    label = sample[1]
    onehot_label = np.zeros(num_classes)
    onehot_label[piece_labels.index(label)] = 1
    labels.append(onehot_label)

  batch = np.array(batch)
  labels = np.array(labels)
  return batch, labels

The generate_batch function takes two arguments, batch_size and empty_prop. It returns a batch of images and their corresponding labels. The labels are one-hot encoded before sending them to the model.

Below is the data_generator function, which is used in training.

def data_generator(batch_size, num_samples, empty_prop):
  i = 0
  while i < num_samples:
      X_batch, y_batch = generate_batch(batch_size, empty_prop)
      i += batch_size
      yield X_batch, y_batch

Step 2: The Model

After several rounds of testing, finetuning, and tweaking, I ended up with the following model.

import keras
from keras.models import Sequential
from keras.layers.core import Dense, Dropout, Activation, Flatten
from keras.layers import MaxPooling2D
from keras.layers.convolutional import Convolution2D
from keras.optimizers import RMSprop
from keras.callbacks import ModelCheckpoint

batch_size = 256
num_classes = 13
epochs = 5
n = 2_000_000
steps_per_epoch = n // batch_size

checkpoint_filepath = "checkpoint.h5"
checkpoint = ModelCheckpoint(checkpoint_filepath, save_weights_only=True, save_best_only=True)

model = Sequential()
model.add(Convolution2D(32, (3, 3), input_shape=(square_size, square_size, 3)))
model.add(Activation("relu"))
model.add(Convolution2D(32, (3, 3)))
model.add(Activation("relu"))
model.add(Convolution2D(64, (3, 3)))
model.add(Activation("relu"))
model.add(Convolution2D(128, (3, 3)))
model.add(Activation("relu"))
model.add(Flatten())
model.add(Dense(256))
model.add(Activation("relu"))
model.add(Dropout(0.5))
model.add(Dense(13))
model.add(Activation("softmax"))

model.compile(loss="categorical_crossentropy", optimizer="adam", metrics=["accuracy"])

history = model.fit_generator(
    generator=data_generator(
        batch_size=batch_size, num_samples=n * steps_per_epoch, empty_prop=0.5
    ),
    validation_data=validation_data_generator(
        batch_size=batch_size, num_samples=1000 * steps_per_epoch, empty_prop=0.5
    ),
    steps_per_epoch=steps_per_epoch,
    validation_steps=1000,
    epochs=epochs,
    verbose=1,
    callbacks=[checkpoint],
)

The model is a sequential CNN with four 2D convolutional layers, each followed by a ReLU activation function. Checkpoints are used to save the best weights.

Step 3: Results

After the first epoch of training, the model achieved an accuracy of 99.00% (validation accuracy was 99.95%). In total, the model was trained for 9 epochs, after which the accuracy was 99.94% (validation accuracy was 100.0%). All in all, that was about 2 hours of gpu time.

Below is the confusion matrix for the test set.

Confusion matrix for the test set.

When testing with images of 64-square chessboards, the model achieved 100.0% on 1,000 random chessboard positions generated using chess-python and FICS games dataset.

Step 4: Creating a FEN string

Now that the model can predict individual squares, we can use it to recognize an entire chessboard. The idea is to divide the chessboard into 64 individual squares, and run them through the model one by one. The model will return a label for each square, which we can then use to create the FEN string for that position.

I used python-chess library to construct the chessboard, and output the FEN string.

from typing import List
import keras
import cv2
import numpy as np
import chess

board_size = 400
square_size = int(board_size / 8)

# Piece labels, lowercase for black, uppercase for white
onehot_labels = ["empty", "k", "q", "r", "b", "n", "p", "K", "Q", "R", "B", "N", "P"]


def restore_onehot(y_pred: np.ndarray) -> np.ndarray:
  y_pred = np.argmax(y_pred, axis=1)
  y_pred = np.array([onehot_labels[i] for i in y_pred])
  return y_pred


def construct_board(labels: List[str]) -> chess.Board:
  board = chess.Board()

  for square, pred_piece in zip(chess.SQUARES, labels):
    color = chess.WHITE if pred_piece.isupper() else chess.BLACK
    if pred_piece == "empty":
      board.remove_piece_at(square)
    elif pred_piece.lower() == "k":
      board.set_piece_at(square, chess.Piece(chess.KING, color))
    elif pred_piece.lower() == "q":
      board.set_piece_at(square, chess.Piece(chess.QUEEN, color))
    elif pred_piece.lower() == "r":
      board.set_piece_at(square, chess.Piece(chess.ROOK, color))
    elif pred_piece.lower() == "b":
      board.set_piece_at(square, chess.Piece(chess.BISHOP, color))
    elif pred_piece.lower() == "n":
      board.set_piece_at(square, chess.Piece(chess.KNIGHT, color))
    elif pred_piece.lower() == "p":
      board.set_piece_at(square, chess.Piece(chess.PAWN, color))

  return board


def extract_squares(image_data: np.ndarray) -> np.ndarray:
  squares = []

  # Split the image into 64 squares
  # We want to go through the squares in the order of A1, A2, A3, ..., H7, H8
  for i in range(7, -1, -1):
    for j in range(0, 8):
      square = image_data[
        i * int(board_size / 8) : (i + 1) * int(board_size / 8),
        j * int(board_size / 8) : (j + 1) * int(board_size / 8),
      ]
      squares.append(square.flatten())

  return np.array(squares).reshape(-1, square_size, square_size, 3) / 255.0


def set_below_confidence_to_empty(
  y_pred: np.ndarray, y_labels: list, confidence: float
) -> list:
  y_max = np.amax(y_pred, axis=1)
  y_dict = {}

  for i in range(0, 64):
    y_dict[chess.SQUARES[i]] = (y_labels[i], y_max[i])

  for square, (_, prob) in y_dict.items():
    if prob < confidence:
      y_dict[square] = ("empty", prob)

  return [x[0] for x in y_dict.values()]


def parse_board(image_data: bytes, to_play: str) -> chess.Board:
  # Read the image and resize it to 400×400
  photo = cv2.imdecode(np.frombuffer(image_data, np.uint8), cv2.IMREAD_COLOR)
  photo = cv2.resize(photo, (board_size, board_size), interpolation=cv2.INTER_AREA)

  # Extract the squares from the image, (reshape & normalize) for the model
  squares = extract_squares(photo)

  # Predict the piece in each square
  y_pred = model.predict(squares)

  # Restore original labels
  y_labels = restore_onehot(y_pred)

  # Heuristics to fix possible errors
  # If the model is not confident (95% or more) about a square, set it to empty
  y_labels = set_below_confidence_to_empty(y_pred, y_labels, 0.95)

  board = construct_board(y_labels)

  # If the board is from the perspective of black, flip it
  if to_play == "black":
    board = board.transform(chess.flip_vertical).transform(chess.flip_horizontal)

  return board

file_to_detect = "test.png"

b = parse_board(file_to_detect, "white")
print(b.fen())

Given the following screenshot of a chessboard as an input, we get this FEN string.

rnb3nr/pp1b1p1p/8/2p1q3/3pP1k1/2PP1N2/PP3P1P/RNBQKB1R

Position used for testing

We can see in the Lichess analysis board that this is the same position as in the image.

Since the model was trained on a wide variety of different piece styles, it is able to recognize even more unusual piece sets, such as in the following example.

2r2rk1/pp2q1pp/4pp2/1b1p4/1n1P1P1N/P3P2Q/1P3RPP/RB4K1

Another position with a more exotic piece set

The model is also able to generalize, and recognize positions scanned from chess books, such as in the example below.

rnbqkb1r/pppppp1p/5np1/8/3P1B2/5N2/PPP1PPPP/RN1qKB1R

Position from a scanned chess book

Although, based on manual testing, detecting from scanned images is highly dependent on the quality of the scan. Any scanning artifacts, low scanning resolution, or skewed scans will increase the error rate.

Step 5: Creating an API

After successfully creating the model, I wanted to create a simple API that would allow me to upload a screenshot of a chessboard, and get a FEN string in return. This API can be deployed to a server, so that I have a quick access to it whenever I need it.

Below is a simple API created with FastAPI. Here is the main API code.

from fastapi import FastAPI, File, UploadFile
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
import chess_eye

app = FastAPI()

app.add_middleware(
  CORSMiddleware,
  allow_origins=["*"],
  allow_credentials=True,
  allow_methods=["*"],
  allow_headers=["*"],
)


class Position(BaseModel):
  fen: str


class Error(BaseModel):
  error: str


@app.post("/api/detect/{color}", response_model=Position)
def detect(
  file: UploadFile = File(...),
  color: str = "white",
):
  if file.content_type not in ["image/jpeg", "image/png"]:
    return Error(error="Invalid file type. Must be JPG, JPEG, or PNG.")

  if color not in ["white", "black"]:
    return Error(error="Invalid color parameter. Must be 'white' or 'black'.")

  image_data = file.file.read()
  fen = chess_eye.get_fen(image_data, color)
  if len(fen) > 0:
    return Position(fen=fen)
  else:
    return Error(error="Unable to detect position")

There are two endpoints: /api/detect/white and /api/detect/black. This decides the direction of the constructed board.

And here is the detection module.

# Code for parse_board() shown in Step 4

def get_fen(image_data: bytes, to_play: str) -> str:
  image_buffer = np.frombuffer(image_data, np.uint8)
  try:
    board = parse_board(image_buffer, to_play)

    # Only include piece placement in the FEN
    fen = board.fen().split(" ")[0]

    return fen
  except Exception as e:
    print(e)
    return ""

And, finally, the Dockerfile to create the Docker image.

FROM python:3.8
RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 && rm -r /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt ./
RUN pip3 install --upgrade pip
RUN pip3 install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

See full code on GitHub.

Step 6: Keyboard shortcut

As an extra, here's a handy way to use the API. I created a macOS Shortcut, that allows me to take a screenshot, and then send it to the API automatically. The FEN string that is returned is then automatically copied to the clipboard, and I can paste it into any chess app.

API shortcut

In Raycast, I bound this shortcut to ⌘+⌥+⇧+C.

A high-level overview of how I trained a deep learning model to detect chess positions from images.

Building Chess Scanner

The Problem

This site was made using Next.js. These blogposts are written using MDX, and they are rendered with next-mdx-remote.
When building the site, Next.js renders the blogposts as HTML using server-side rendering. Upon visiting a page, the static HTML is initially served to the client, after which the page is hydrated, allowing for interactive React components otherwise not possible with static HTML.

This build-time rendering has advantages, such as fast initial load time (before hydration), improved SEO, and making the content accessible even if JavaScript is disabled.
The disadvantage of this approach is that the content of the blogpost is effectively included twice in the page: once as static HTML in the page source, and the second time as compiled MDX (JSX), embedded in the __NEXT_DATA__ object at the bottom of the page, which is used when hydrating the page.

For example, the __NEXT_DATA__ object in this blogpost is 1.16 MB, the majority of it being the compiled MDX source.
Going through the compiled MDX source, I noticed that some parts of it contained a lot of whitespace, which seemed unnecessary (see image below). Reducing the size of the compiled MDX source should result in a smaller __NEXT_DATA__ object, and thus a smaller page size, making it faster to load.

Compiled MDX source embedded in the page.

The solution

The solution was to minify the compiled MDX source in getStaticProps, before passing it to the page.
Here's the getStaticProps function I was using with my blog posts:

export const getStaticProps = async ({ params }) => {
  const postFilePath = path.join(NOTES_PATH, `${params.slug}.mdx`);
  const source = fs.readFileSync(postFilePath);

  const { content, data } = matter(source);
  const mdxSource = await compileMDX(content, data);

  return {
    props: {
      source: mdxSource,
    },
  };
};

I used terser to minify the compiled MDX source. The updated code looks like this:

import { minify } from "terser";

// ...

export const getStaticProps = async ({ params }) => {
  const postFilePath = path.join(NOTES_PATH, `${params.slug}.mdx`);
  const source = fs.readFileSync(postFilePath);

  const { content, data } = matter(source);
  const mdxSource = await compileMDX(content, data);

  mdxSource.compiledSource = (
    await minify(mdxSource.compiledSource, {
      parse: {
        bare_returns: true,
      },
      toplevel: true,
    })
  ).code;

  return {
    props: {
      source: mdxSource,
    },
  };
};

With this, the size of the __NEXT_DATA__ object of the same blogpost is now 515 kB, which is less than half of the original size. Looking at the compiled MDX source, the whitespace is now effectively gone (see image below).

Compiled MDX source after minification.

After building the site with, I checked the size of the static HTML file of the blogpost. The results are shown in the table below.

Original MDX Minified MDX Size reduction
__NEXT_DATA__ object 1.16 MB 515 kB 55.6%
Static HTML 809.41 kB 460.62 kB 43.1%

Wrapping Up

In conclusion, minifying the compiled MDX source is a simple yet effective way to cut down on page size, and make your site faster to load.

How I reduced page sizes of my blogposts by almost a half.

Reducing the size of MDX data in Next.js

The Problem

I have an API running in a Docker container. I would like to review the API logs and, if possible, design a dashboard to display critical metrics. The solution should be self-hosted, as I want to keep my data private.

The solution

The following stack will be used:

Loki to store and index the API logs.
Promtail to collect the logs from the API and send them to Loki.
Grafana to visualize the logs and create dashboards.

Here is a diagram of the stack:

Stack diagram

Prerequisites

Before you can set up the analytics, you must make sure your API is logging to a file. Here's a simple example of writing logs to a file in Python, using the built-in logging module.

import logging

# Initializing the logger
logger = logging.getLogger("api")
logger.setLevel(logging.INFO)

handler = logging.FileHandler("/var/log/api.log")
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
handler.setFormatter(formatter)

logger.addHandler(handler)

# Logging something
if res.status_code == 200:
  logger.info("API call successful")
else:
  logger.error("API call failed")

In the example above, the logs will be written to /var/log/api.log in the Docker container.
We need to configure Promtail to collect these logs and send them to Loki. To do that, we will create a shared Docker volume between the API container and the Promtail container. The API container will write the logs to the volume, and Promtail will read the logs from the volume and pass them to Loki.

docker volume create api_logs

We then mount the volume to the API container in the docker-compose.yml file:

volumes:
  - api_logs:/var/log

Now, the logs will be written to the volume.

Setting up Promtail, Loki, and Grafana

We will create a new project directory for our analytics stack.

mkdir analytics
cd analytics

We will create a docker-compose.yml file with the following contents:

version: "3.8"
services:
  loki:
    restart: always
    image: grafana/loki:latest
    command: -config.file=/etc/loki/local-config.yaml
    volumes:
      - loki_data:/loki

  promtail:
    restart: always
    image: grafana/promtail:latest
    volumes:
      - api_logs:/var/log
      - ./promtail-config.yaml:/etc/promtail/config.yml
    command: -config.file=/etc/promtail/config.yml
    depends_on:
      - loki

  grafana:
    restart: always
    image: grafana/grafana:latest
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: admin
    volumes:
      - grafana_data:/var/lib/grafana
      - grafana_config:/etc/grafana
    depends_on:
      - loki

volumes:
  api_logs:
    external: true
  loki_data:
  grafana_data:
  grafana_config:

networks:
  default:
    external: true
    name: hyades

Here, we set up the three services of our analytics stack: Loki, Promtail, and Grafana. We also create the necessary volumes so that the data is persisted between restarts.
Make sure to configure the network to match the network of your API container. In my case, the network is called hyades. Also, open ports if you need to. For Loki, you need to open port 3100, and for Grafana, port 3000.

We will also create a promtail-config.yaml file with the following contents:

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: api
    static_configs:
      - targets:
          - api
        labels:
          job: api
          __path__: /var/log/api.log

The __path__ label is used to tell Promtail which file to read the logs from. In our case, it's /var/log/api.log, i.e. the file we configured the API to write logs to.

Now, we can start the analytics stack:

docker-compose up -d

Setting up Grafana

Grafana should now be accessible at port 3000. After logging in with the default credentials, admin:admin, you will be prompted to change the password.

Adding Loki as a data source

Click on the hamburger menu in the top left corner, and select Connections.

Grafana Connections

In the left sidebar, click on Data sources, and then click on Add data source.

Adding a data source

From the list, select Loki. In the HTTP section, enter http://loki:3100 as the URL. Scroll to the bottom of the page, and click on Save & Test. If everything is configured correctly, you should see a green Data source connected and labels found. message.

Configuring Loki URL

You have now successfully added Loki as a data source in Grafana. Check out the Grafana documentation to learn how to analyze and visualize your logs.

How to configure Loki, Promtail, and Grafana to analyze logs from your API.

Adding self-hosted log analytics to your API

If you ever run into problems, where you cannot connect to the internet from your Docker container, one reason might be incorrectly set MTU value between the host and Docker. On my host, the MTU value is set to 1462, but Docker uses 1500 by default.

Start by editing docker.service.

sudo nano /lib/systemd/system/docker.service

Change the following line,

ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

by adding --mtu=1462.

ExecStart=/usr/bin/dockerd --mtu=1462 -H fd:// --containerd=/run/containerd/containerd.sock

Save the file, and restart Docker.

sudo systemctl daemon-reload
sudo systemctl start docker
sudo systemctl restart docker

At this point, if you have existing networks in Docker, they are still using the default 1500 value. You have to re-create your networks, but this time, specifying the MTU value like so.

docker network create <NAME OF NETWORK> --opt com.docker.network.driver.mtu=1462

Possible fix when you cannot connect to the internet from your Docker container.

Change MTU value in Docker

Recently I was working on a project that required me to run a headful
Chrome instance (via Puppeteer) inside a Docker container. To keep the container as
small and lightweight as possible, I avoided installing a desktop environment
inside the container.

What originally seemed like a simple task turned out to be a bit more
complicated than I expected. Anyway, after some trial and error, I
managed to get it working.

The Dockerfile

The Dockerfile is pretty straightforward. It's based on the official
debian:latest image.

FROM debian:latest

ENV DEBIAN_FRONTEND=noninteractive

# Install dependencies
RUN apt-get update && \
    apt-get install -y \
    xvfb \
    chromium

ADD xvfb-chromium /usr/bin/xvfb-chromium
RUN ln -s /usr/bin/xvfb-chromium /usr/bin/google-chrome && \
    ln -s /usr/bin/xvfb-chromium /usr/bin/chromium-browser && \
    chmod +x /usr/bin/xvfb-chromium && \
    chmod +x /usr/bin/google-chrome

Be sure to include line 3, ENV DEBIAN_FRONTEND=noninteractive. This
will prevent the installation of any dependencies from hanging.

On line 11, we add a script called xvfb-chromium to the container (make sure it's in the same directory as the Dockerfile).
This script will be used to launch Chrome. This is script is taken from
Atlassian's docker-chromium-xvfb repository.

#!/bin/bash

_kill_procs() {
  kill -TERM $chromium
  wait $chromium
  kill -TERM $xvfb
}

# Setup a trap to catch SIGTERM and relay it to child processes
trap _kill_procs SIGTERM

XVFB_WHD=${XVFB_WHD:-1280x720x16}

# Start Xvfb
Xvfb :99 -ac -screen 0 $XVFB_WHD -nolisten tcp &
xvfb=$!

export DISPLAY=:99

chromium --no-sandbox $@ &
chromium=$!

wait $chromium
wait $xvfb

With this, you should now be able to run a headful Chrome instance inside the container, for example, via Puppeteer.

How to run a headful Chrome instance inside a Docker container without installing a desktop environment

Headful Chrome Inside a Docker Container

Extract audio from MP4 files in the current directory

Extracts audio from all MP4 files in the current cirectory.

for i in *.mp4; do ffmpeg -i "$i" -vn -acodec copy "${i%.*}.aac"; done

FLAC to ALAC

Converts all FLAC files in the current directory to ALAC, preserving metadata.

for f in *.flac; do ffmpeg -i "$f" -c:a alac "${f%.flac}.m4a"; done

FLAC to MP3

Converts all FLAC files in the current directory to MP3 files with 320 kbps bitrate, preserving metadata.

for f in *.flac; do ffmpeg -i "$f" -ab 320k -map_metadata 0 -id3v2_version 3 "${f%.flac}.mp3"; done

A collection of useful audio-related ffmpeg one-liners

Useful ffmpeg one-liners

First, install the pycryptodome package.

pip install pycryptodome

The Code

import hashlib
from Crypto.Cipher import AES


def pad(data: bytes) -> bytes:
    length = AES.block_size - (len(data) % AES.block_size)
    return data + (chr(length) * length).encode()


def unpad(data: bytes) -> bytes:
    length = data[-1]
    return data[:-length]


def bin_to_base16(bin_data: bytes) -> str:
    return bin_data.hex()


def base16_to_bin(base16_data: str) -> bytes:
    return bytes.fromhex(base16_data)


def encrypt(message: str, password: str) -> str:
    message_bytes = pad(message.encode("utf-8"))
    password_bytes = hashlib.sha256(password.encode("utf-8")).digest()

    cipher = AES.new(password_bytes, AES.MODE_ECB)
    return bin_to_base16(cipher.encrypt(message_bytes))


def decrypt(encrypted_message: str, password: str) -> str:
    password_bytes = hashlib.sha256(password.encode("utf-8")).digest()

    cipher = AES.new(password_bytes, AES.MODE_ECB)
    message = cipher.decrypt(base16_to_bin(encrypted_message))

    return unpad(message).decode("utf-8")


Encrypt a message

encrypted_message = encrypt("Hello, World!", "password")
print(encrypted_message)

The output will be 2cd9a476c50ea46f0d826e54578e0d63.

Decrypt a message

decrypted_message = decrypt("2cd9a476c50ea46f0d826e54578e0d63", "password")
print(decrypted_message)

The output will be Hello, World!.

Encrypt and decrypt messages with a passphrase in Python

Search for Posts and Notes