iconizr

is an – at present: proof-of-concept – command line tool that helps you prepare your vector based SVG icons for use with the widest possible range of devices. It takes a folder of SVG files and processes them to a bunch of files including

• cleaned versions of the original SVG icons (optional),
• a single compact SVG icon sprite,
• single PNG icons (optional),
• a combined PNG icon sprite,
• several CSS files with different formats inlcuding
  • SVG single image icons (optional),
  • SVG data URIs,
  • SVG sprite references,
  • PNG single image icons (optional),
  • PNG data URIs and
  • PNG sprite references,
• Sass variants of these CSS files for easy inclusion into your Sass project,
• an HTML fragment including some JavaScript for asynchronously loading the most appropriate icon variant
• and finally an HTML/PHP preview page for testing the different icon variants.

To leverage iconizr to the greatest extent possible, some additional tools have to be installed on the system independently (see below).

iconizr is written in (namespaced) PHP and meant to be used on the (Linux) command line (i.e. with the PHP CLI SAPI). To be honest, there was only one reason making me go for PHP: It is what I know best. Im sure there are quite some other fancy modern languages and techniques one could use for achieving the same, but I guess I'm just not smart enough for those. Having said this, I'd welcome anyone contributing a port of iconizr.

Getting started

As iconizr is written in PHP, there's nothing much of an installation process. Just put the iconizr.phps script (along with it's accompanying files and directories) to a location of your liking and make sure that it may be executed by setting the proper file permissions. If you'd like to simplify the invocation of iconizr you might create a symlink into your local executables directory, e.g.:

ln -s /path/to/iconizr.phps /usr/local/bin/iconizr

Run iconizr by calling the script with the apropriate command line options (see below). Please consider that – for security reasons – the output directory has to be a sub(sub)directory of the current working directory, so change your working directory first if necessary:

cd /path/to/website/docroot
/path/to/iconizr.phps --css --out css source/svg

or using the symlink mentioned above:

iconizr --css --out css source/svg

This will take all the SVG files found in /path/to/website/docroot/source/svg and render the resulting CSS files and sprites to the directory /path/to/website/docroot/css (and below). For the sake of simplicity, Sass files have been omitted in this example.

Documentation

Usage:

iconizr [options] input/dir1 [input/dir2 ...]

Short	Long	Value	Description
-o	--out	Directory path	Provide the path of the output directory here. For security reasons, the output directory has to be a sub(sub)directory of the current working directory. If it doesn't exist, iconizr will try to create it. Along with the input directory this is a mandatory argument.
	--sassout	Directory path	If you want the Sass files to be created in a separate directory, then specify it using this argument. The same restrictions apply as for the standard output directory. If you don't specify this argument, the Sass files will be created in the standard output directory.
-c	--css	String (optional)	If this argument is given, several CSS files will be generated. By default, the filenames will all start with "iconizr" (e.g. "iconizr-svg-data.css"). If you provide a string value for this argument (e.g. "myproject"), this value will be used as the prefix for all generated CSS files (e.g. "myproject-svg-data.css").
-s	--sass	String (optional)	Identical to the -c argument, but applying to the generation of Sass files.
-p	--prefix	String	This is the prefix used for all CSS class names generated. It defaults to "icon", so that a SVG file named example.svg results in a CSS class named "icon-example".
-l	--level	Integer	This is the optimization level for PNG files. It has to lie between 0 and 11 (inclusive) and defaults to 4, with 0 meaning "no optimization", 1 meaning "fast & rough" and 11 meaning "slow & high quality". Setting this to a high value may result in a very long processing time.
-q	--quantize		If given, iconizr will quantize PNG images (i.e. convert them to 8-bit color depth; please see the requirements for this). The quantized images are only used if they are smaller in file size than their the originals (and this is not necessarily the case for all PNG files). Quantization may also impact the visual image quality, so please make sure to compare the result to the original images.
-r	--root		If given, iconizr will use the CSS output directory as root-relative path in the stylesheet loader HTML fragment (i.e. /path/to/icons.css instead of path/to/icons.css).
	--svg	Integer	This is the maximum length a SVG data URI may have. If only one icon exceeds this threshold, all data URIs of this icon set will be changed to external SVG sprite references. Defaults to 1048576 (1MB), minimum is 1024 (1kB).
	--png	Integer	This is the maximum length a PNG data URI may have. If only one icon exceeds this threshold, all data URIs of this icon set will be changed to external PNG sprite references. Defaults to 32768 (32KB = Internet Explorer 8 limit), minimum is 1024 (1kB).
-d	--dims		If given, a second CSS rule for each icon will be created, setting the dimensions of the icon (via the width and height properties).
	--width	Integer	Default width for icons (in pixel) in case the SVG file is missing a value. Must be between 1 and 1000 (including).
	--height	Integer	Default height for icons (in pixel) in case the SVG file is missing a value. Must be between 1 and 1000 (including).
-k	--keep		During the compilation of the SVG and PNG sprites, iconizr also creates intermediate SVG and PNG versions of each single icon. Usually, these intermediate files are deleted at the end of the compilation process. If you want to keep these files for some reason, just add this argument. In this case, also an additional set of stylesheets will be created (both CSS and/or Sass), which uses these single image icons (carrying the suffix -single.html). However, it is not recommended to use these stylesheets for production systems, and you should always prefer the CSS sprite or data URI variants for performance reasons. The single image icon stylesheets will also be ignored by the stylesheet loader JavaScript, but at least you will be able to select them explicitly using the icon kit preview documents.
-v	--verbose	Integer (optional)	By default, iconizr operates quietly without any output. If you specify this argument (optionally using the value "1"), some simple status messages will be printed. Use "2" as value to even print the console output of the external tools being used (like e.g. pngcrush or pngquant).
	--scour	String	iconizr can use either SVGO or Scour for cleaning the original SVG files. As far as I can tell, Scour yields slightly better results (i.e. smaller SVG files) than SVGO. As Scour is rather a Python script than an executable, you need to provide the full script path via this option if you want to use it (also, of course, Python has to be available on the system; see requirements).
	--python	String	When using Scour for cleaning the original SVG files, you need to have Python 2 handy, as Scour is based on this version and hasn't been updated for quite a while. If your default Python binary is not version 2, you need to specify the absolute path to an alternative version 2 binary with this parameter.

Examples

Comparison to grunticon

While doing pretty much the same as the Filament Group's / Scott Jehl's grunticon, iconizr especially focuses on reducing the size of files and number of HTTP requests, addressing mobile devices in particular:

1. SVG files are cleaned and freed from a lot of cruft typically introduced by SVG editing application before they get converted to data URIs or embedded into the SVG sprite.
2. PNG files are losslessly optimized (and optionally quantized to 8-bit files) before being used in data URIs or the PNG sprite.
3. As soon as even one of the icons needs to be loaded externally (due to exceeding a potential data URI size limitation), all icons will get loaded via the corresponding sprite.

Evtl. kein Limit für data-URIs bei SVG? Welcher Browser mit SVG-Support hat das kleinste data-URI-Limit?

Rendering mode		grunticon	iconizr
PNG images / sprite	Requests	11	2
	Size (KB)	33.3 / 31.2	20.0 / 21.1
PNG data URI	Requests	1	1
	Size (KB)	30.1 / 41.1	20.3 / 29.7
SVG sprite	Requests	-	2
	Size (KB)	-	42.8 / 496.0
SVG data URI	Requests	1	1
	Size (KB)	126.0 / 1,913.0	49.4 / 720.0

Requirements

For iconizr to run, you will need some programs installed on your machine. These are:

• PHP (kinda obvious)
• PhantomJS (for rendering PNG images of your SVG drawings)

For SVG optimization you will need either of the following (or both):

• SVGO (which needs Node.js ...)
• Scour (which needs Python 2 ...)

For PNG optimization you should have as many of the following as possible:

• Pngcrush
• pngquant
• OptiPNG

Resources

There are some useful resources on data URIs in general:

• Data URIs
• Data URI support
• Data URI limitation to 128kB on iPhone / Safari 3.0
• Data URI limitation checker to test which data URI size is supported by your device

As soon as I'll find some time I will do some tests in our Open Device Lab to see if there are any device specific data URI limitations.

Resources on SVG support:

• Can I use SVG

Legal

iconizr by Joschi Kuphal is licensed under a Creative Commons Attribution 3.0 Unported License. Follow @jkphl on Twitter to keep updated.