Generate PNG icons from icon fonts like Font Awesome
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
extra
fonts
iconserver
.gitignore
LICENCE
README.md
TODO
config.py
icon.png
preview.html
requirements.txt
run.py
run.wsgi
setup.sh
siteconfig.sample.py

README.md

Icon Generator

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.

Installation

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.)

Configuration

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.

Icons

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.

API

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.

Examples

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

Maintenance

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.

Icon fonts

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.

Licence and thanks

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

Notes

I've tried several other webfonts with this application with lesser or greater success. Entypo/Entypo Social in particular do not work.