
## 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](https://grafana.com/oss/loki/) to store and index the API logs.
- [Promtail](https://grafana.com/docs/loki/latest/clients/promtail/) to collect the logs from the API and send them to Loki.
- [Grafana](https://grafana.com/) to visualize the logs and create dashboards.

Here is a diagram of the stack:

![Stack diagram](/images/diagram.svg)

## 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.

```python title="Writing to a logfile in Python"
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.

```shell title="Creating a shared volume"
docker volume create api_logs
```

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

```yaml title="Mounting the volume to the API container"
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.

```shell title="Creating a new project directory"
mkdir analytics
cd analytics
```

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

```yaml title="docker-compose.yml"
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:

```yaml title="promtail-config.yaml"
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:

```shell title="Starting 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](/images/grafana-connections.png)

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

![Adding a data source](/images/add-source.png)

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](/images/configure-loki.png)

You have now successfully added Loki as a data source in Grafana. Check out the [Grafana documentation](https://grafana.com/docs/grafana/latest/) 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


## The Problem

This site was made using [Next.js](https://nextjs.org). These blogposts are written using <abbr>[MDX](https://mdxjs.com)</abbr>, and they are rendered with [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote).
When building the site, Next.js renders the blogposts as <abbr>HTML</abbr> using server-side rendering. Upon visiting a page, the static <abbr>HTML</abbr> is initially served to the client, after which the page is hydrated, allowing for interactive React components otherwise not possible with static <abbr>HTML</abbr>.

This build-time rendering has advantages, such as fast initial load time (before hydration), improved <abbr>SEO</abbr>, 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 <abbr>HTML</abbr> in the page source, and the second time as compiled <abbr>MDX</abbr> (<abbr>JSX</abbr>), 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](/blog/building-chess-scanner) is 1.16 MB, the majority of it being the compiled <abbr>MDX</abbr> source.
Going through the compiled <abbr>MDX</abbr> 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 <abbr>MDX</abbr> 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.](/images/next_data.png)

## The solution

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

```javascript
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](https://www.npmjs.com/package/terser) to minify the compiled <abbr>MDX</abbr> source. The updated code looks like this:

```javascript {1, 12-19}
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 <abbr>MDX</abbr> source, the whitespace is now effectively gone (see image below).

![Compiled MDX source after minification.](/images/minified_next_data.png)

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

<div class="font-sans">

|                        | 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% |

</div>

## Wrapping Up

In conclusion, minifying the compiled <abbr>MDX</abbr> 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


#### Project Links

<Linked href="https://github.com/einoko/chess-scanner">
  GitHub repository
</Linked>

<Linked href="https://chess-scanner.sumi.re/docs">API documentation</Linked>

The API is currently deployed at [`https://chess-scanner.sumi.re`](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](https://lichess.org/analysis) or Stockfish? I could install a browser extension like [Chessvision.ai](https://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

1. As an input, the program receives a cropped image of a chessboard.
2. The image is evenly divided into an 8×8 grid, i.e. each cell is one square on the chessboard.
3. A multiclass classifier is run on each square, determining the piece (if any), on that square.
4. From this, a chessboard is constructed, and the position is returned as a <abbr>[FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation)</abbr> 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](https://lichess.org) and [Chess.com](https://chess.com) are the most popular online chess websites, I decided to use their boards and piece sets for training.

<Download href="/files/training.zip">
  Download training files (training.zip)
</Download>

![White knights in various styles.](/images/white_knights.png)

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 <abbr>PNG</abbr> 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.

```python
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 <abbr>PNG</abbr> 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.

```python
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.](/images/chess_pieces_hq.png)

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

```python
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.

```python
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.

```python
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 <abbr>CNN</abbr> 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 <abbr>gpu</abbr> time.

Below is the confusion matrix for the test set.

![Confusion matrix for the test set.](/images/conf-matrix.png)

When testing with images of 64-square chessboards, the model achieved 100.0% on 1,000 random chessboard positions generated using `chess-python` and [<abbr>FICS</abbr> games dataset](https://www.kaggle.com/datasets/astoeckl/fics-chess-games).

## 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 <abbr>FEN</abbr> string for that position.

I used `python-chess` library to construct the chessboard, and output the <abbr>FEN</abbr> string.

```python
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
```

```python title="Detecting the position from an image"
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 <abbr>FEN</abbr> string.

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

![Position used for testing](/images/test_chessboard.png)

We can see in the [Lichess analysis board](https://lichess.org/analysis/standard/rnb3nr/pp1b1p1p/8/2p1q3/3pP1k1/2PP1N2/PP3P1P/RNBQKB1R_w_KQ_-_0_1) 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.

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

![Another position with a more exotic piece set](/images/test_chessboard_2.png)

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

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

![Position from a scanned chess book](/images/test_chessboard_3.png)

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 <abbr>API</abbr> that would allow me to upload a screenshot of a chessboard, and get a <abbr>FEN</abbr> string in return. This <abbr>API</abbr> can be deployed to a server, so that I have a quick access to it whenever I need it.

Below is a simple <abbr>API</abbr> created with FastAPI. Here is the main <abbr>API</abbr> code.

```python title="main.py"
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.

```python title="chess_eye.py"
# 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.

```docker title="Dockerfile"
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](https://github.com/einoko/chess_scanner).

## Step 6: Keyboard shortcut

As an extra, here's a handy way to use the <abbr>API</abbr>. I created a [macOS Shortcut](https://support.apple.com/en-gb/guide/shortcuts-mac/apdf22b0444c/mac), that allows me to take a screenshot, and then send it to the <abbr>API</abbr> automatically. The <abbr>FEN</abbr> string that is returned is then automatically copied to the clipboard, and I can paste it into any chess app.

![API shortcut](/images/chess-shortcut.png)

In [Raycast](https://www.raycast.com/), I bound this shortcut to <kbd>⌘</kbd>+<kbd>⌥</kbd>+<kbd>⇧</kbd>+<kbd>C</kbd>.


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

Building Chess Scanner


## The Problem

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

<YouTube id="_-AfhLQfb6w" />

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 words<Sidenote>While this list does not include _every_ word, it is good enough for this purpose.</Sidenote>. As seen in the video, some of the words in the word list were questionable at best. There were words such as <abbr>FLDXT</abbr>, <abbr>HDQRS</abbr>, <abbr>EXPWY</abbr>, (short for _fluid extraxt_, _headquarters_, and _expressway_). Due to this, Parker later decided to use the word list of [Wordle](https://www.nytimes.com/games/wordle/index.html) 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](#full-code)). I first downloaded the same [word list that Parker used](https://github.com/dwyl/english-words/blob/master/words_alpha.txt), 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. <abbr>CLA<ins>SS</ins></abbr>, need to be filtered out as well, as they break the rules of the puzzle.

```javascript title="index.js"
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 <abbr>SLATE</abbr> becomes <abbr>AELST</abbr>, 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, <abbr>a</abbr> to <abbr>z</abbr>. 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](https://github.com/lemire/FastBitSet.js/).

```javascript title="Creating the word index"
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)),
  });
}
```

```js title="Removing anagram words"
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.

```js
// 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 <abbr>fjord – gucks – nymph – vibex – waltz</abbr> 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

<Download href="/files/five-words.zip">Project files (.zip)</Download>

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

```shell title="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


## 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](https://nextjs.org/). Styling is done with [Tailwind CSS](https://tailwindcss.com/). The blog posts are written in [MDX](https://mdxjs.com/), 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: <span className="font-sans">[IBM Plex Sans](https://www.ibm.com/plex/)</span> for UI elements and headers, [Literata](https://fonts.google.com/specimen/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</a> for code blocks.

## Post Features

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

```yaml
---
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](https://rehype-pretty-code.netlify.app/) plugin.

{/* prettier-ignore */}
````jsx
```javascript title="Add two numbers" {2}
const add(a, b) => {
  return a + b;
}
```
````

#### Output

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

### Mathematical equations

Mathematical equations are rendered using [$\KaTeX$](https://katex.org/). Use `$` for inline equations and `$$` for display equations.

```markdown
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:

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

#### Output

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

<Alert type="normal" title="Zoom zoom">
  All images wider than 780 pixels are wrapped around a
  [react-medium-image-zoom](https://github.com/rpearce/react-medium-image-zoom)
  component for a nice zoom effect. Try clicking on the image.
</Alert>

### Footnotes

You can use footnotes as follows:

```markdown
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.

<Alert type="normal" title="On Footnotes">
  Note, that the footnotes are rendered at the [bottom of the
  page](#references). If you are using this style of footnotes, place a `##
  References` or a similar header at very last line of your post, to create a
  header for the footnotes. Note, that there is also an option for [Tufte-style
  sidenotes](#sidenotes) (see below), which provide the same functionality. Try
  to decide which one you prefer, as using both will probably confuse your
  reader.
</Alert>

## MDX Components

### Alert boxes

#### Exclamation

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

#### Output

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

#### Warning

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

#### Output

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

#### Info

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

#### Output

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

#### Info (no color)

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

#### Output

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

### Collapsible section

```jsx title="Code"
<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

<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>

### Links

You can use styled link components to display links.

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

#### Output

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

### Bordered area

You can create a bordered area for styled text.

{/* prettier-ignore */}
```jsx
<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 */}
<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>

### 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.

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

#### Output

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

### 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 <abbr>HTML</abbr>, i.e. no Twitter trackers are loaded, and it stays up even if the original Tweet is deleted. Idea from [Josh Comeau](https://www.joshwcomeau.com/blog/how-i-built-my-blog/).

#### Code

{/* prettier-ignore */}
```jsx
<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.
</Tweet>

### 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 */}
```html
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 officia<Sidenote>This is a sidenote. On desktop, it will be shown on the right, on smaller screens it is displayed within the text.</Sidenote> 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.