From df89f4eabd20cd9c0f9f0fbf09b0edb96621614d Mon Sep 17 00:00:00 2001
From: Christoph Hagen <github@christophhagen.de>
Date: Sun, 15 Jan 2023 15:00:31 +0100
Subject: [PATCH] Add readme

---
 Readme.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 Readme.md

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..e306d39
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,81 @@
+# Cap Server
+
+A simple server to manage a collection of bottle caps, including their names, images, and a classifier to recognize them by image.
+Works together with the companion app [Caps-iOS](https://christophhagen.de/git/ch/Caps-iOS).
+A description of the project is provided [on my website](https://christophhagen.de/projects/software/caps/en.html).
+
+## Overview
+
+The server maintains the cap database of all bottle caps that I've collected so far, and allows me to add new caps, images and classifiers using the associated [iOS App](https://christophhagen.de/git/ch/Caps-iOS).
+
+It currently has the following functions:
+- Provide the data (name, id, image count, ...) for all existing caps
+- Serve a representative image for each cap, and maintain the image catalog for classifier training
+- Add new caps through the iOS App
+- Add new images through the app
+- Rename caps and change the main image
+- Protect the database from changes through token-based authentication
+- Host a classifier model to download for offline cap classification
+- Upload new classifiers when trained on a different system using CreateML
+- Provide a script to train a new classifier on the current image set
+- Provide an HTML snippet which can be embedded in a website to show the current cap count ([see here](https://christophhagen.de/projects/software/caps/en.html))
+- Provide a webpage showing a grid of all caps, where mosaic images can be created.
+
+## Configuration
+
+The server is configured using a configuration file `config.json` located in the `Resources` folder:
+
+```json
+{
+    "port" : 6001,
+    "maxBodySize" : "2mb",
+    "logPath": "\/var\/log\/caps.log",
+    "serveFiles": true,
+    "writers" : [
+        "auth_key_1"
+    ]
+}
+```
+
+The `writers` array contains a list of strings acting as access tokens to restrict operations where data is mutated (adding images, changing information, updating the classifier).
+
+## Mosaic
+
+The server provides a simple web page where visitors can arrange the existing bottle caps in a grid, to create mosaic images from the caps.
+It allows loading and saving arrangements locally, and has the option to display the average color of the caps.
+
+You can try it [here](https://christophhagen.de/caps/grid.html).
+
+Note: The data for the mosaic is currently not updated automatically, since Swift on Linux has no built-in tools to create JPGs. The thumbnails are created when a new classifier is trained.
+
+## Classifier training
+
+The main server is running on Linux, which doesn't provide the CreateML framework required for classifier training. 
+This has to be done on macOS using the `train.swift` script in the `Training` folder.
+It will:
+- Fetch the current image catalog by checking missing and changed images
+- Train a classifier on the image set
+- Increment the classifier version and upload the new model
+- Update the list of caps which can be recognized using the classifier
+- Create missing thumbnails for each cap for the cap grid
+
+A configuration file is required to run the training, with a valid access token for the server:
+
+```json
+{
+    "imageDirectory": "../Public/images",
+    "classifierModelPath": "../Public/classifier.mlmodel",
+    "trainingIterations": 20,
+    "serverPath": "https://mydomain.com/caps",
+    "authenticationToken": "mysecretkey",
+}
+```
+
+The configuration file `config.json` must be located in the folder from which the script is run.
+
+```bash
+swift train.swift
+```
+
+## Future work
+- Create thumbnails on the server using [JPEG](https://github.com/kelvin13/jpeg)