export.md

To keep maintenance effort low for Osmic the repository contains only the base or "source" versions of icons. All the derivative versions can be generated by using a script.

This Python export script (tools/export.py) enables you to create your own customised collection of icons. It is able to:

• include exactly the icons in the export you want to have
• add padding
• add halos/outlines
• add shields
• re-colour icons
• create icon sprites
• create an icon font with the help of Font Custom
• export as SVG and PNG (through rsvg or Inkscape) with different resolutions including retina (double sized) versions.

All parameters can be changed through a YAML configuration file. There are several examples in the config/ folder at the same location as the script:

• font.yaml creates an icon font of all icons.
• josm.yaml exports coloured icons with halos for the Osmic JOSM style.
• osm-carto-png.yaml exports icons as PNG and re-colours them according to the colour scheme of openstreetmap-carto.
• osm-carto-svg.yaml exports icons in SVG format like they are currently used in openstreetmap-carto i.e. with 1px padding and without halo.
• osm-carto-svg-color.yaml exports icons in SVG format like they are currently used in openstreetmap-carto i.e. with 1px padding and without halo and re-colours them according to their colour scheme.
• overpass-turbo-png.yaml exports icons in PNG format for Overpass Turbo, all in the same colour with halos, retina version and without subdirectories.
• shields.yaml exports icons with shields.
• small-collection.yaml exports a subset of icons demonstrating the ability to specify which icons exactly should be included in the export.
• sprites.yaml exports the icons in a sprite like this one.

Such a configuration file must be supplied to the script as parameter e.g. execute ./tools/export.py tools/config/shields.yaml in the main folder of Osmic. Additionally the following parameters can be specified at the command line (execute export.py -h for details):

• a working directory parameter with --basedir
• a input base directory parameter with --input
• a output base directory parameter with --output

The configuration file follows a simple organisational pattern for maximum versatility: all global icon parameters can be overridden by parameters specific to a certain icon id (except for sprites where only the colour can be changed). This is e.g. how re-colouring of icons works. An example of this pattern can be found in osm-carto-png.yaml where the global fill colour of #734a08 is changed for the icon id peak to #d08f55.

In the following all possible parameters are listed. All of them are optional. Colour values can be either specified as RGB value e.g. rgb(255, 255, 255) or #ffffff, as HSL value e.g. hsl(20, 40%, 33%) or as perceptual HUSL value (http://www.husl-colors.org/) e.g. husl(20, 40%, 33%).

• basedir - specify the working directory, if not specified it defaults to the current working directory, relative and absolute paths are allowed, relative paths are evaluated against the current working directory

• input_basedir - specify the input base directory, if not specified it defaults to the current working directory, can be either an absolute or relative path

• input - specify a list of directory names from which the icon files are read, useful if only a subset of icons should be processed, if not specified the script reads icons from the base directory. Each directory has the following parameters:

  • name - specify the directory name, if not specified the directory will be skipped
  • include - specify a list of file names with or without size (e.g. waste-basket or waste-basket-14) that should be included in the export, if not specified and no exclude list is present (see below) all icons in this directory are included. If no size for an icon is specified all sizes of this icon are included.
  • exclude - specify a list of file names with or without size (e.g. waste-basket or waste-basket-14) that should be excluded from the export, if not specified and no include list is present (see above) all icons in this directory are included. If no size for an icon is specified all sizes of this icon are excluded.
  • include and exclude may never be specified together for a directory, otherwise the directory will be skipped.

• output_basedir - specify the output base directory, if not specified it defaults to ./export, can be either an absolute or relative path

• empty_output - specify whether the output base directory should be emptied of all contents, the value must be either true or false, if not specified it defaults to false, WARNING: deletes all files in the output base directory if it already exists, be careful with existing data as all sample config files currently use this option!

• format - is either png, svg, sprite or font, if not specified it defaults to png

• dpi - specify the resolution in dots per inch (dpi), if not specified it defaults to 90

• retina - specify whether double sized (retina) versions should be generated, the value must be either true or false, if not specified it defaults to false, makes only sense to specify for format: "png" or format: "sprite", it is ignored otherwise

• subdirs - specify whether the icons will be kept in their subdirectories or are exported all in the same directory, if not specified it defaults to true (meaning icons are kept in their subdirectories)

• size_filter - specify the size version (e.g. 14 for all icon-id-14.svg) which should be included in the output - all other sizes are left out, if not specified no filter is applied (for font output there is a default filter of 14 active)

• global_style - a list of global styles such as padding, halo, fill colour etc. for each icon, the following parameters are sub-elements of global_style or an icon id element e.g. hunting-stand.

  • padding - specify the number of pixels of space between the icon shape and canvas border, the icon stays centred all the time, only values > 0 are allowed, defaults to 0

  • fill - specify a colour value for the icon fill e.g. #efefef, if not specified the colour fill stays black

  • opacity - specify the opacity of the icon fill in values of 0 (transparent) .. 1 (opaque), if not specified it defaults to 1.0

  • halo - a list of styles related to icon halos/outlines such as fill colour, width and opacity

    • fill - specify a colour value for the halo fill e.g. #efefef, if not specified the colour fill defaults to white
    • width - specify the width of the halo in pixels, if not specified it defaults to 0 which means no halo will be added
    • opacity - specify the opacity of the halo in values of 0 (transparent) .. 1 (opaque), if not specified it defaults to 0.3

  • shield - a list of styles related to icon shields such as fills and strokes

    • fill - specify a colour value for the shield fill e.g. #efefef, if not specified the colour fill defaults to black
    • opacity - specify the opacity of the shield fill in values of 0 (transparent) .. 1 (opaque), if not specified it defaults to 1.0
    • stroke_fill - specify a colour value for the stroke fill e.g. #efefef, if not specified no stroke will be drawn
    • stroke_width - specify a stroke width in pixels, only values > 0 are allowed, if not specified no stroke will be drawn
    • stroke_opacity - specify the opacity of the stroke in values of 0 (transparent) .. 1 (opaque), if not specified it defaults to 1.0
    • rounded - specify the corner radius of the shield, only values > 0 are allowed, if not specified defaults to 0 (unrounded corners)
    • padding - specify number of pixels of space between the icon shape and shield border, the icon stays centred all the times, only values > 0 are allowed, defaults to 0

• sprite - a list of styles such as columns and padding for generating sprites, makes only sense to specify for format: "sprite", it is ignored otherwise

  • cols - specify the number of columns of the sprite i.e. how many icons will be displayed in one row, only values > 0 are allowed, if not specified defaults to 12
  • outer_padding- specify the padding at the outer border of all icons, only values > 0 are allowed, if not specified defaults to 4
  • icon_padding- specify the padding between the different icons, only values > 0 are allowed, if not specified defaults to 4
  • background- specify a colour value for the sprite background fill e.g. #efefef, if not specified it defaults to transparent
  • filename- specify the filename of the sprite, if not specified defaults to sprite

• font - a list of configuration options for icon font generation

  • output_basedir - specify the output directory for the font files, if not specified it defaults to ./font, can be either an absolute or relative path

Dependencies

• husl (pip install husl) if you want to specify HUSL colour values.