Sugar-iconify

This page has been migrated to the Sugar Labs wiki. This is an archive (and likely, out-of-date) copy of material found at http://wiki.sugarlabs.org/go/Sugar_iconify . Please edit and comment on it there. If you disagree with its migration, please explain why on its talk page.

The sugar-iconify.py script converts SVGs into the format required for Sugar icons, adding the necessary stroke and fill entities. This is a Python script, and as such requires Python to run.

Usage

sugar-iconify.py [-ceghipv] [-s stroke_hex] [-f fill_hex] [-m | -o ] [-d directory] input.svg

Description

This script will create Sugar-compatible SVG icons from input.svg by adding the appropriate stroke and fill entities. It has two primary modes of operation: single-icon and icon set. For additional information about creating an SVG suitable for passing as the input to this script, see the tutorial on Making Sugar Icons.

Single-icon: The default operation creates a single sugar icon — for instance an activity icon — from the input SVG. By default, the Sugarized icon will be written to a new file named input.sugar.svg, optionally in the output directory specified with -d. By invoking the -o option, the input file will be overwritten in place.

When run, the script attempts to determine the proper hex values for the stroke and fill entities, and asks for confirmation before proceeding. You can preemptively accept this guess with -g, but do so with caution as the proper values cannot be determined with 100% confidence; we strongly recommend against using this in conjunction with the -o option. Should the script be unable to determine the proper entities, you can specify the correct stroke and fill hex values to replace using the -s and -f flags, respectively. Finally, for activity icons, you may find it convenient to apply the recommended default stroke and fill colors (#666666, #FFFFFF) to the output SVG with -c, which will make your icon match the visual style of uninstantiated activities within the UI, as well as the others posted on the wiki.

You may also generate an HTML preview containing a few variations on the icon rendering style, as it may later be seen in Sugar. When the -x flag is passed, a directory named input.preview containing several example SVGs and the HTML file will be created, adjacent your icon output. View this file in Safari or Firefox (other browsers not tested), and observe the tips listed in the preview for validating your icon. At present, HTML previews are only supported for single-icon conversions, and -x will be ignored when passed with the -m flag.

Icon sets: Activity developers may require many icons for placement in toolbars and elsewhere in their activities. To make the process of creating and exporting large numbers of icons easier, this script provides a multiple-export feature. When the -m option is passed, the script will export an entire set of icons from a single input SVG — one for each top level group within it. The resulting files will each contain all of the appropriate stroke and fill entities, and assume the name of the id given to the group that defined it.

In some cases, you may desire to update a single icon, or a subset of the icons defined within a given SVG. To do so, pass a pattern to the script with -p, and only those icons which match the pattern will be exported.

Options

-c    Apply default color entities (#666666, #FFFFFF) to output

-d    [directory] The preferred output directory

-e    Do not insert entities for strokes and fills

-f    [hex] Hex value to replace with fill entity

-g    Automatically accept guesses for stroke and fill entities

-h    Display this help message

-i    Insert "isolated stroke" entities

-m    Multiple export; export top level groups as separate icons

-o    Modify input file in place, overwriting it; overridden by -m

-p    [pattern] Only export icons whose name contains pattern

-s    [hex] Hex value to replace with stroke entity

-v    Verbose

-x    Create HTML preview files, for icon validation

Examples

To do a simple single activity icon conversion, automatically applying the suggested default colors to the output:

      sugar-iconify.py -c activity-hello_world.svg

If the script cannot infer the proper stroke and fill values (and assuming your icon has red stroke, green fill):

      sugar-iconify.py -c -s '#FF0000' -f '#00FF00' activity-hello_world.svg

To export an icon set, resulting in a separate icon for each top level layer/group in input.svg:

      sugar-iconify.py -m toolbar_icons.svg

By adding the -p flag, you can export a subset of the total icon set by name (eg. edit-copy, edit-paste, edit-...):

     sugar-iconify.py -m -p edit toolbar_icons.svg

For detailed feedback about the entity replacements being made, add -v:

     sugar-iconify.py -cv input.svg

To overwrite the input file, use -o; otherwise the output file will be named input.sugar.svg:

     sugar-iconify.py -co input.svg

To generate an HTML preview of your icon, with tips for validation:

    sugar-iconify.py -x input.svg