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. A description of the project is provided on my website.

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.

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)
• 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:

{
    "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.

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:

{
    "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.

swift train.swift

Future work

• Create thumbnails on the server using JPEG