Upload Lichess FEN square classifier

README.md

@@ -0,0 +1,86 @@
+---
+license: agpl-3.0
+tags:
+- chess
+- computer-vision
+- fen
+- lichess
+- mlx
+- safetensors
+library_name: mlx
+pipeline_tag: image-classification
+---
+
+# ChessCV Lichess FEN Square Classifier
+
+This repository contains an MLX chess-board square classifier for FEN recognition from Lichess-style 2D board screenshots.
+
+The model classifies each 32×32 RGB board-square crop into one of 13 classes: empty square plus the 12 standard chess pieces. A full FEN can be produced by running the classifier over all 64 square crops in board order and converting the predicted class sequence into piece-placement notation.
+
+## Model file
+
+- `mlx_model_lichess_fen.safetensors` — MLX weights for `ChessPieceCNN`
+- `mlx_model.py` — minimal MLX model definition
+- `labels.json` — class-index mapping
+- `training_config.json` — high-level training metadata
+
+## Labels
+
+```text
+0: empty
+1: white pawn
+2: white rook
+3: white knight
+4: white bishop
+5: white queen
+6: white king
+7: black pawn
+8: black rook
+9: black knight
+10: black bishop
+11: black queen
+12: black king
+```
+
+## Input format
+
+- Shape: `(N, 32, 32, 3)`
+- Color: RGB
+- Value range: float32 normalized to `[0, 1]`
+
+For board-level FEN recognition, crop the detected board into 64 squares, resize each crop to 32×32, run a batch inference pass, then map argmax outputs to FEN piece-placement symbols.
+
+## Example usage
+
+```python
+import mlx.core as mx
+import numpy as np
+from mlx_model import ChessPieceCNN
+
+model = ChessPieceCNN()
+model.load_weights("mlx_model_lichess_fen.safetensors")
+
+# batch: np.ndarray shaped (64, 32, 32, 3), RGB, float32 in [0, 1]
+logits = model(mx.array(batch))
+mx.eval(logits)
+labels = np.argmax(np.array(logits), axis=1)
+```
+
+## Training data summary
+
+The model was trained on synthetic square crops generated from Lichess piece assets, with extra emphasis on the default Lichess piece style. The dataset includes occupied and empty squares, varied Lichess-like board colors, scale changes, compression artifacts, blur, lighting/gamma variation, and small-screen resampling effects.
+
+Final training run:
+
+- Samples: 240,000
+- Epochs: 16
+- Empty-square samples: ~42%
+- Final training accuracy: 94.96%
+
+## Intended use
+
+This model is intended as a component in chess computer-vision pipelines that detect a 2D chessboard on screen and reconstruct the piece-placement part of a FEN string.
+
+## License and source assets
+
+The model was trained using Lichess piece assets from the open-source Lichess project. Lichess is distributed under AGPL-3.0-or-later; individual piece sets may have their own original author/license history upstream.

labels.json

@@ -0,0 +1,15 @@
+{
+  "0": "empty",
+  "1": "wP",
+  "2": "wR",
+  "3": "wN",
+  "4": "wB",
+  "5": "wQ",
+  "6": "wK",
+  "7": "bP",
+  "8": "bR",
+  "9": "bN",
+  "10": "bB",
+  "11": "bQ",
+  "12": "bK"
+}

mlx_model.py

@@ -0,0 +1,30 @@
+import mlx.core as mx
+import mlx.nn as nn
+
+class ChessPieceCNN(nn.Module):
+    def __init__(self, num_classes=13):
+        super().__init__()
+        self.conv1 = nn.Conv2d(3, 32, 3, padding=1)
+        self.bn1 = nn.BatchNorm(32)
+        self.conv2 = nn.Conv2d(32, 64, 3, padding=1)
+        self.bn2 = nn.BatchNorm(64)
+        self.conv3 = nn.Conv2d(64, 128, 3, padding=1)
+        self.bn3 = nn.BatchNorm(128)
+        self.pool = nn.MaxPool2d(2, 2)
+        
+        self.fc1 = nn.Linear(128 * 4 * 4, 256)
+        self.fc2 = nn.Linear(256, num_classes)
+
+    def __call__(self, x):
+        # x input is (B, H, W, C)
+        x = nn.relu(self.bn1(self.conv1(x)))
+        x = self.pool(x)
+        x = nn.relu(self.bn2(self.conv2(x)))
+        x = self.pool(x)
+        x = nn.relu(self.bn3(self.conv3(x)))
+        x = self.pool(x)
+        
+        x = mx.flatten(x, start_axis=1)
+        x = nn.relu(self.fc1(x))
+        x = self.fc2(x)
+        return x

mlx_model_lichess_fen.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9395c7b2121bae026182e7169af3fb907ff1b2752e9b5db2458dcdb0a7c76d38
+size 2489811

training_config.json

@@ -0,0 +1,14 @@
+{
+  "architecture": "ChessPieceCNN",
+  "framework": "MLX",
+  "input_shape": [32, 32, 3],
+  "num_classes": 13,
+  "target_platform": "Lichess-style 2D chess boards",
+  "samples": 240000,
+  "epochs": 16,
+  "empty_square_probability": 0.42,
+  "default_lichess_piece_set": "cburnett",
+  "final_training_loss": 0.1234,
+  "final_training_accuracy": 0.9496,
+  "normalization": "RGB float32 in [0, 1]"
+}