82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
|
# 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)
|