Webservice to generate PNG icons from icon fonts, such as Font Awesome.
(It can of course also generate icons from fonts that contain normal letters.)
It is built with Python and Flask and designed to run as a WSGI application behind a proper web server.
Clone the repository and run setup.sh in the root directory. This will create the virtualenv and install the necessary dependencies (from requirements.txt) with pip. Note: The Pillow library is required, so please ensure that your system has the libraries required to compile Pillow. (The *-dev libraries can be removed after installation.)
After installation you must edit siteconfig.py. This file is not included in the repo, but is created by setup.sh (a copy of siteconfig.sample.py. It overrides the settings in config.py. At minimum, you must override MAX_CACHE_SIZE to a non-zero number, or the application will not run.
The server includes the Font Awesome, Elusive Icons and Typicons fonts and corresponding JSON configuration files and CSS files.
Additional icon font packages are available in the iconpacks repo.
To add a new font, add the webfont files (TTF, WOFF etc.) to the iconserver/static/fonts directory, the CSS file for the webfont (which defines the classes for each icon/character) to iconserver/static/css and create a corresponding JSON configuration file in /fonts.
Such a configuration file looks like this:
{
"id": "fontawesome",
"name": "Font Awesome",
"ttf": "fontawesome-webfont.ttf",
"credit": "Dave Gandy",
"url": "http://fortawesome.github.io/Font-Awesome/",
"licence": "http://scripts.sil.org/OFL",
"css": "font-awesome.css",
"cssclass": "fa fa-{name}",
"characters": {
"adjust": "f042",
"adn": "f170",
"align-center": "f037",
"align-justify": "f039",
"align-left": "f036",
"align-right": "f038",
"ambulance": "f0f9",
"anchor": "f13d",
"android": "f17b",
// etc.
}
}All values are required. Their meaning is as follows:
| Key | Meaning |
|---|---|
id |
URL-friendly name of the font. Must be lowercase, e.g. fontawesome, elusive |
name |
User-friendly name of the font, e.g. Font Awesome, Elusive Icons |
ttf |
The filename, not the path, of the TTF file. The file must be in the iconserver/static/fonts directory, e.g. Elusive-Icons.ttf |
credit |
The person/company who created the font. Shown on the preview page, e.g. Aristeides Stathopoulos, Dave Gandy |
url |
The URL of the author's homepage. Shown on the preview page, e.g. http://fortawesome.github.io/Font-Awesome/, http://typicons.com/ |
licence |
The URL of the font's licence, e.g. http://scripts.sil.org/OFL |
css |
The filename, not the path, of the font's CSS file. The file must be in the iconserver/static/css directory, e.g. typicons.css, font-awesome.css |
cssclass |
A template for the CSS class that should be applied to the span element showing the character preview. {name} will be replaced with the character name, e.g. fa fa-{name} |
characters |
A mapping of the character names to the hex Unicode codepoint, e.g. e600, f01d. What you would use in CSS as \<value> or in Python as \u<value> |
The JSON file can usually be created easily enough from the font's CSS file (Sublime Text's multiple cursors are a big help here).
To make it a little easier, you can instead generate a TSV file with each line containing the name and the Unicode codepoint of a character, and use the extra/generate.py script to generate the JSON characters mapping from that.
In most cases, the CSS file for the font will need editing to set the font-size to 48px. The line-height attribute may also need changing. See the included CSS files for examples.
The API is very simple:
http://www.example.com/icon/<fontname>/<csscolour>/<character-name>[/<size>][.png]
fontname, csscolour and character-name are mandatory. size is optional, as is the .png extension.
fontname corresponds to the id value in the JSON configuration file, csscolour is a CSS colour of xxx or xxxxxx form (without preceding #), and character-name is the name of a character as specified in the JSON configuration file. size is the size of the icon in pixels (all icons are square).
csscolour is case-insensitive and may be 3 or 6 characters long.
If size is not specified, the value of SIZE set in config.py or siteconfig.py will be used. If API_ALLOW_SIZE is set to False, the size parameter will be ignored and SIZE will be used.
All icons are in PNG format. You may append .png to the URL if you need to.
The /icon endpoint will 302 redirect the client to the static path of the requested icon, generating the icon first if necessary. By default this is the URL http://www.example.com/static/icons/<fontname>/<colour>/<character-name>-<size>.png, corresponding to the directory tree under iconserver/static/icons.
You can alter the directory icons are saved to and the corresponding URL with the CACHEDIR and CACHEURL options in siteconfig.py (overriding the defaults in config.py).
If CACHEDIR and CACHEURL are specified, they will be used thus: (CACHEDIR|CACHEURL)/<fontname>/<colour>/<character-name>.png.
All arguments are converted to lowercase and the colour is normalised to the 6-character form to ensure each icon is only generated and cached once.
http://www.example.com/icon/fontawesome/fff/beer
http://www.example.com/icon/fontawesome/F0F0F0/beer.png
http://www.example.com/icon/elusive/010101/briefcase
http://www.example.com/icon/elusive/000/podcast/1024
The application itself does not monitor or manage the cache size, but the extra/purge_cache.py script will reduce the size of the icon cache to 50% of the MAX_CACHE_SIZE you've specified in siteconfig.py, preferentially deleting the least recently-accessed icons.
Call it with extra/purge_cache.py path/to/icon/cache/directory (by default iconserver/static/icons) from cron.
It will delete the least recently-accessed icons and then remove any empty directories.
The following fonts are included with the server:
Some additional fonts, including GitHub's Octicons and Material Design, can be downloaded from the icon pack repo.
This code is made available under the MIT Licence. The bundled fonts are released under the SIL Open Font Licence (OFL).
It goes without saying that this app would be both pointless and impossible without the awesome work of the fonts' creators.
| Font | Author |
|---|---|
| Elusive Icons | Aristeides Stathopoulos |
| Font Awesome | Dave Gandy |
| Typicons | Stephen Hutchings |
I've tried several other webfonts with this application with lesser or greater success. Entypo/Entypo Social in particular do not work.